Welcome to the Cookbook

The CookBook depends on contributions from people just like you. This application was designed to allow anybody to recommend and add changes as necessary. If you're new to CakePHP you can make a difference and are one of the best people to suggest a change to the docs. Submissions are reviewed by members of the documentation team for consistency, accuracy and wording.

Before you dive in and rewrite the book though, there are some notes and guidelines to keep in mind:

• Be succinct. People are looking for answers quickly and don't want to read large blocks of text to get to the answer.
• You can submit plain text (paragraphs), it will be html formatted automatically
• Chunk your content. Break up your content to make it easier to scan. Use sub-sections, code blocks, lists, and tables appropriately.
• Wrap inline code with <code> tags. Don't use quotes around the code. For example, "The <code>$uses</code> variable specifies which models to use."
• Wrap code blocks with <pre> tags. For example:
  

      <pre>
  	$this->functionName();
  	$this->otherFunctionName();
      </pre>
  

  It's not necessary to escape pre contents

• File and URL paths should be wrapped in <kbd> tags.
• Use example.com when a generic domain name needs to be referenced. Its purpose is to be generic and will never be linked to a spam or porn site. (see RFC 2606)
• Links to other resources in the book should be without the domain. Eg. /view/181/built-in-helpers
• Code examples should conform to CakePHP Coding Standards.
• Use predefined classes method, warning and note.
• And finally: Check the preview! If it doesn't look right to you - it won't look right when it's reviewed.

There are certain elements that can be given special attention. These require a special class attribute to be applied to the element.

Warnings should be used to let the user know about something that is important such as indicating that a method or property is deprecated. It could also be used to point out where certain usage might create adverse effects.

Example:

This method has been deprecated. Please use methodName.

<p class="warning">This method has been deprecated. Please use <a href="#">methodName</a>.</p>

1. <p class="warning">This method has been deprecated. Please use <a href="#">methodName</a>.</p>

Alternatively, if you have a warning that spans across multiple block elements then use a DIV to wrap all elements.

Example:

<div class="warning">
   <p>This approach may create serious performance degradation. Consider alternative approaches:</p>
   <ul>
      <li>Approach A</li>
      <li>Approach B</li>
   </ul>
</div>

1. <div class="warning">
2. <p>This approach may create serious performance degradation. Consider alternative approaches:</p>
3. <ul>
4. <li>Approach A</li>
5. <li>Approach B</li>
6. </ul>
7. </div>

A note can be used to highlight information that a reader should know or be aware of when developing their application.

Example:

You can add conditions to any of the methods to narrow down your results.

<p class="note">You can add conditions to any of the methods to narrow down your results.</p>

1. <p class="note">You can add conditions to any of the methods to narrow down your results.</p>

A note that needs to span across multiple block elements should use a DIV that wraps all elements. See the previous section for example.

The method class should be used to wrap the method statement, parameters, and return value. The class is only applied to a single paragraph element.

Example:

string render (array $options = array())

<p class="method">
   <code>string render (array $options = array())</code>
</p>

1. <p class="method">
2. <code>string render (array $options = array())</code>
3. </p>

Pre tags are assumed to contain php code unless otherwise specified

There are however other classes which can be used for pre tags specifcally:

plain for plain text. I.e. entering:

<pre class="plain">
Plain text
With self entered carriage return
</pre>

Gives:

Plain text
With self entered carriage return

shell for shell commands. I.e. entering:

<pre class="shell">
$ cake bake shell code
</pre>

Gives:

$ cake bake shell code

The cookbook's fixed texts are stored in the application itself, and are not editable via the website. If you'd like to, for example, change the text for a menu item for your language - find the po file in the source repository fork the cakebook project, make your changes and let someone know in #cakephp-docs so that your changes can be pulled into the main repository.

Stub - update me

If a section of the book hasn't been translated into your language yet it will appear in English. The CookBook relies on submissions from users just like you to share and add to the information accumulated here. See Contributing to the CookBook for general guidelines on submissions.

Stub - add notes regarding sync markers

The following is a list of shortcuts which point to custom queries on the CakePHP Lighthouse (ticket tracking) site. These queries help break down the mass of tickets into smaller groups, categorized by subject matter. These links point only to tickets which are currently open, sorted from oldest to newest.

"Tiny URLs" for the queries are provided (in addition to the direct URLs) as a convenience for copying and pasting into the various communication channels used by the community.

• Please be advised that all enhancement tickets for created 1.3 are being pushed to 2.0.
• Please note that enhancement tickets are no longer accepted for 1.1, 1.2 or 1.3 as they are stable releases.

The best way to help out is by creating tests and patches, which can be submitted as tickets via Lighthouse. This will ease the burden on the core development team. Refer to the Testing section within the Cookbook which covers how to install SimpleTest and how to create test cases. It's important that your tests be verified on the latest version of CakePHP, available via GitHub.

If you feel more comfortable/skilled/knowledgeable in a certain category listed below, bookmark the link and browse the tickets within that category. It is possible to submit test cases and patches for other people's tickets once you have registered on the Lighthouse site — it could help bring resolution to an outstanding bug or highly sought after enhancement.

You must be registered on lighthouse to be able to submit a ticket. Register here.

• Ask someone in the irc channel for help confirming it is a bug and not a simple error/misunderstanding.
• Search the google group archives to see if someone has already solved your problem.
• Send an email (post a message) to the google group to see if anyone else has seen the issue.
• Check the current tickets to see if your bug has already been reported.
• Look at the Timeline to see if the problem you experienced has already been fixed.
• Verify your version of CakePHP. If you are not using the latest code (http://code.cakephp.org/source) try updating to the newest stable or obtaining the HEAD of the relevant git branch see if your problem is already fixed.

There are a small number of people who actually develop CakePHP. In between documenting, planning, answering questions, developing features for new releases and sometimes pretending that they have lives outside of CakePHP, bugs tend to be last on a very long to-do list for them. To catch the eye of one of these few volunteers, you'll need to take to heart a few tips on how to report a bug so that they can and will help you.

Please note the word volunteer :). The people who are going to help you with a bug are volunteers. Not only are you not paying them to help you, but nobody else is either. So, be nice to them.

Beyond that golden rule, what follows are some additional tips on ways to make your bug report better so that someone will be able to help you.

There are three basic parts of a bug report which can greatly reduce the amount of time spent finding the solution: You need to be specific in describing what you did, what you were expecting, and why it didn't meet your expectations. If you don't provide this information, then we have to guess and we all know that doesn't work too well. :)

• Report one problem in each bug report.
• If you have encountered two bugs that don't appear to be related, create a new bug report for each one. This makes it easier for different people to help with the different bugs.
• Please select the appropriate values for the ticket properties that match your problem. Pay special attention to the Component, Milestone and Version values.
• Valid test cases are a great help, patches are invited. Test cases and patches included together with a ticket are preferred.

View Current Tickets

Report a bug

The following is a list of shortcuts which point to custom queries on the CakePHP Trac (ticket tracking) site. These queries help break down the mass of tickets into smaller groups, categorized by subject matter. These links point only to tickets which are currently open, sorted from oldest to newest.

"Tiny URLs" for the queries are provided (in addition to the direct URLs) as a convenience for copying and pasting into the various communication channels used by the community.

1. Available Reports
2. Tickets Related To The Official Web Sites [tinyurl]

1. Bugs [tinyurl]
2. Documentation [tinyurl]
3. Enhancements [tinyurl]
4. Optimizations [tinyurl]
5. Other [tinyurl]

1. ACL and Auth [tinyurl]
2. Console and Shells [tinyurl]
3. Controllers and Components [tinyurl]
4. Core [tinyurl]
   
5. Databases [tinyurl]
6. Models and Behaviours [tinyurl]
7. Plugins and Vendors [tinyurl]
8. Views and Helpers [tinyurl]
9. Web Server Administration [tinyurl]

1. Bugs [tinyurl]
2. Documentation [tinyurl]
3. Other [tinyurl]