Common mistakes while working with CakePHP index page views

At some point of time as developers, we all go through a situation where we have a short deadline and a hand-full of work. In such situations if we are working with CakePHP index views, this blog may help you avoid some common mistakes. For this tutorial, we are targetting CakePHP 2 and CakePHP 3.


  • Knowledge on CakePHP views

Mistake #1: Displaying record ID number on the alert message

We all know that CakePHP has an excellent feature of generating code automatically using baking. After baking, in the index view for any model the delete action code will look as follows,

In CakePHP 2.x

In CakePHP 3.x (upto 3.2)

Now, if we try to delete the record from index page, it displays the record ID number on the alert box as shown below.


This may not be understandable to the users, especially if we hide the record ID column on the list or if the list has another column which contains integers as values.

It is always a good practice to display the record name on the alert box. This way the users can easily identify the record that they are going to delete.

This can be done by replacing the following code in the delete action’s html on the index.ctp file.

In CakePHP 2.x

In CakePHP 3.x (upto 3.2)

Then the alert box will be displayed as shown below,


This is certainly way more understandable than what we had earlier.

Mistake #2: Clearing search text from the search box after displaying search results

Having a custom search for our index lists is quite common. Our controller’s action takes the search text as an input, creates the conditions array for the paginate() method and returns the result. The user would expect that after he searches, the search text box would still have the value that he had searched for, but since clicking on the search button causes a postback to the server the value is lost. This can be fixed by adding the below line to our controller’s index action,

In both CakePHP 2.x and 3.x (upto 3.2)

and in the view file, update the search text box element as below,

In both CakePHP 2.x and 3.x (upto 3.2)

That’s all! From now onwards the search box retains its value between searches.

Mistake #3: Not handling the search after moving to certain page using pagination

The solution below will not support CakePHP 3.2  & higher versions. Please see the Update section in this blog for the solution to support CakePHP 3.0 & above versions.

Consider we have custom search along with pagination for users. Imagine the user does the following –

  1. Goes to the index page.
  2. Goes to page number 10
  3. Searches for

You’ll probably get a 404 not found error. This is because upon moving to a certain page, CakePHP appends the page number to the URL in the address bar as shown below,


Now, if we make a search on the list, CakePHP tries to load results with the given page number in the URL. If our search results are less in number and can fit in pages below the specified page number in the URL, we’ll see a 404 error,


This makes sense since there are no records to load with the given page number.

We can easily handle this issue by following below steps on click of the search button,

  1. Store the search key in a session variable.
  2. Redirect to the index page.
  3. Perform the search operation by retrieving the search key from the session variable.

The code to do this looks like the following,

In both CakePHP 2.x and 3.x (upto 3.2)

Next, in the controller’s index action we need to add the following before building $conditions  array.

In both CakePHP 2.x and 3.x (upto 3.2)

Done! Now we can perform custom search after moving to any page using the pagination, without any problems.

Mistake #4: Losing search conditions on using pagination

This is quite opposite to Mistake #3. Imagine our users list has both pagination and custom search. To reproduce this issue, follow the steps given below,

  1. Search the list
  2. Now move to another page using the pagination.

You’ll notice that we loose search conditions and paginate() returns results without the search parameters. This is because the pagination component doesn’t read our custom search text value when we change the page number.

A simple working solution to this problem is to add the search key as a query string to the URL with help of PaginatorHelper’s options array.

Add following line to your view template,

In CakePHP 2.x

In CakePHP 3.x (upto 3.2)

and in controller’s action, we will get the search key from URL using named parameters as shown below,

In CakePHP 3.x (upto 3.2)

That’s it.

Mistake #5: Not exporting all the records due to pagination

Suppose we have added an export functionality to our list along with the pagination. If we use the same index action to export the data it will export only the records that are visible on the first page of the index list. This is because of pagination’s default limit.

If we want to export whole list, either filtered list or normal, we can achieve it by modifying the $paginate options limit and maxLimit to a value that we want,

In both CakePHP 2.x and 3.x (upto 3.2)


We hope you enjoyed the tutorial and learnt something that’ll help you avoid some common mistakes during your next CakePHP development.

Update (November 2017)

As CakePHP 3 latest versions are using query string parameters to store the redirect URL instead of the session variable, we are setting the query string value of the page number to the first page.

The following solution supports all the CakePHP 3 versions to avoid Mistake #3

In CakePHP 3.x

Posted By: Sirisha Grandhe, Osmosee

Are you interested? follow us and get notified of new posts

2 thoughts on “Common mistakes while working with CakePHP index page views

Leave A Reply

7 + nineteen =