Fork me on GitHub
Heads up!
These docs are for Crud v3 - that only works with CakePHP 2.x. For CRUD v4 docs please go to the new documentation site
The CRUD v4 documentation has been completely rewritten, and since CRUD v3 and CRUD v4 API is ~95% identical, it may be worth a look for CRUD v3 users as well until v4 docs are backported for v3.
...toc....

Introduction

This is a Crud version of the cakephp blog tutorial part one and part two.

It’s meant to show that everything the example does in Controller is done automatically by Crud, and that it even provides a more flexible and robust solution.

This example is not meant to be a introduction to cakephp, but more an easy way to compare bake & hand-crafted code vs. crud.

This is obviously a very simple example, and doesn’t showcase all the features of Crud.

Please dive into the documentation for more information.

Installation & Configuration

Please follow the installation guidelines on how to get the Crud plugin

Add the following to your AppController.php (php5.4) or follow the installation guidelines for alternative installation methods.

<?php
App::uses('Controller', 'Controller');
App::uses('CrudControllerTrait', 'Crud.Lib');

class AppController extends Controller {
	use CrudControllerTrait;

	public $components = array(
		'Crud.Crud' => array(
		 	'actions' => array(
				'index', 'add', 'edit', 'view', 'delete'
			)
		)
	);

}
?>

Basic tutorial

This part covers the basic introductional blog example, nothing more, nothing less.

Initialize the database

Create a table with some sample data with the following SQL:

CREATE TABLE posts (
    id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    title VARCHAR(50),
    body TEXT,
    created DATETIME DEFAULT NULL,
    modified DATETIME DEFAULT NULL
);

/* Then insert some posts for testing: */
INSERT INTO posts (title,body,created)
    VALUES ('The title', 'This is the post body.', NOW());
INSERT INTO posts (title,body,created)
    VALUES ('A title once again', 'And the post body follows.', NOW());
INSERT INTO posts (title,body,created)
    VALUES ('Title strikes back', 'This is really exciting! Not.', NOW());

Post Model

Create app/Model/Post.php

<?php
App::uses('AppModel', 'Model');

class Post extends AppModel {
    public $validate = array(
        'title' => array(
            'rule' => 'notBlank'
        ),
        'body' => array(
            'rule' => 'notBlank'
        )
    );
}
?>

Post Controller

Create app/Controller/PostsController.php

<?php
App::uses('AppController', 'Controller');

class PostsController extends AppController {
	public $components = array('Paginator');
}
?>

Post Views

Since Crud is bake compatible, we can just bake the views:

Console/cake bake view Post

Done

That was it… the 15 minute blog tutorial done with Crud.

Obviously there isn’t a huge win in this small example, but read on and see how much awesome features Crud can provide.

Read on and let’s add an API layer on top of our new Blog.

Adding API

Since our new blog is super webscale, and we want people to be able to consume our content through a nice API, we want to add some JSON and XML response formats.

Route configuration

We need to tell CakePHP router that we want to handle JSON and XML extensions.

<?php
Router::parseExtensions('json', 'xml');
?>

Modify AppController

We need to attach the cakephp request handler and the crud api listener by modifying the AppController::$components array.

<?php
public $components = array(
	'RequestHandler', // <- new
	'Crud.Crud' => array(
	 	'actions' => array(
			'index', 'add', 'edit', 'view', 'delete'
		),
		'listeners' => array( // <- new
			'api' => 'Crud.Api'
		)
	)
);
?>

And that’s it… we’ve now got a nice REST API for our posts controller, or any other controller your application could have.

Using the new API

Reading posts in XML or JSON is as easy as using http://your-site-domain.com/posts.xml for XML or http://your-site-domain.com/posts.json for JSON.

JSON API

By adding ‘.json’ to your URLs CakePHP and Crud will make sure that all responses is in JSON.

List posts

Simply request /posts.json and you will get a list of posts in JSON format.

curl -I -X GET http://your-site-domain.com/posts.json

Add post

Simply POST to /posts/add.json

curl -I -X POST http://your-site-domain.com/posts/add.json \
	-d title="My new JSON API blog post" \
	-d body="With an epic body"

HTTP/1.1 201 Created
Server: nginx/1.4.1
Date: Sun, 16 Jun 2013 12:17:12 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: 43
Connection: keep-alive
Set-Cookie: CAKEPHP=qp2dpvkpkqqk81mdn3iajdals2; expires=Sun, 16-Jun-2013 16:17:12 GMT; path=/; HttpOnly
Location: http://your-site-domain.com/posts/view/5

{
  "success": true,
  "data": {
    "Post": {
      "id": "5"
    }
  }
}

Validation errors

Example on how validation errors in JSON looks

In this example, I left out the body field

curl -I -X POST http://your-site-domain.com/posts/add.json \
	-d title="My new JSON API blog post"

HTTP/1.1 400 Bad Request
Server: nginx/1.4.1
Date: Sun, 16 Jun 2013 12:25:12 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: 69
Connection: keep-alive
Set-Cookie: CAKEPHP=vevclsl2o6r7h4v7uon9j5tkd1; expires=Sun, 16-Jun-2013 16:25:12 GMT; path=/; HttpOnly

{
  "success": false,
  "data": {
    "body": ["This field cannot be left blank"]
  }
}

XML API

By adding ‘.xml’ to your URLs CakePHP and Crud will make sure that all responses is in XML

List posts

Simply request /posts.xml and you will get a list of posts in XML format.

curl -I -X GET http://your-site-domain.com/posts.xml

Add post

Simply POST to /posts/add.xml

curl -I -X POST http://your-site-domain.com/posts/add.xml \
	-d title="My new XML API blog post" \
	-d body="With an epic body"

HTTP/1.1 201 Created
Server: nginx/1.4.1
Date: Sun, 16 Jun 2013 12:17:12 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: 43
Connection: keep-alive
Set-Cookie: CAKEPHP=qp2dpvkpkqqk81mdn3iajdals2; expires=Sun, 16-Jun-2013 16:17:12 GMT; path=/; HttpOnly
Location: http://your-site-domain.com/posts/view/5

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <success>1</success>
  <data>
    <Post>
      <id>6</id>
    </Post>
  </data>
</response>

Validation errors

Example on how validation errors in XML looks

In this example, I left out the body field

curl -I -X POST http://your-site-domain.com/posts/add.xml \
	-d title="My new XML API blog post" \

HTTP/1.1 400 Bad Request
Server: nginx/1.4.1
Date: Sun, 16 Jun 2013 12:27:44 GMT
Content-Type: application/xml; charset=UTF-8
Content-Length: 138
Connection: keep-alive
Set-Cookie: CAKEPHP=3i5p02o6ove6dhohmb11acq765; expires=Sun, 16-Jun-2013 16:27:44 GMT; path=/; HttpOnly

<?xml version="1.0" encoding="UTF-8"?>
<response>
	<success>0</success>
	<data>
		<body>This field cannot be left blank</body>
	</data>
</response>



comments powered by Disqus