cakephp / docs Goto Github PK

View Code? Open in Web Editor NEW

677.0 70.0 2.6K 76.32 MB

CakePHP CookBook

Home Page: http://book.cakephp.org

License: Other

Makefile 85.10% Python 10.93% Dockerfile 3.90% Vim Script 0.06%

cakephp documentation hacktoberfest

docs's Introduction

CakePHP Documentation

This is the official documentation for the CakePHP project. It is available online in HTML, PDF and EPUB formats at https://book.cakephp.org.

Contributing to the documentation is pretty simple. Please read the documentation on contributing to the documentation over on the cookbook for help. You can read all the documentation within as it is just in plain text files, marked up with ReST text formatting.

There are two ways for building the documentation: with Docker, or by installing the packages directly on your OS.

Build the Documentation with Docker

Docker will let you create a container with all packages needed to build the docs. You need to have docker installed, see the official docs of docker for more information.

Build the image locally

Starting in the top-level directory, you can build the provided Dockerfile and tag it with the name cakephp/docs by running:

docker build -t cakephp/docs .

This can take a little while, because all packages needs to be downloaded, but you'll only need to do this once.

Now that the image is built, you can run all the commands to build the docs:

To build the html:

docker run -it --rm -v $(pwd):/data cakephp/docs make html

To build the epub:

docker run -it --rm -v $(pwd):/data cakephp/docs make epub

To build the latex:

docker run -it --rm -v $(pwd):/data cakephp/docs make latex

To build the pdf:

docker run -it --rm -v $(pwd):/data cakephp/docs make pdf

All the documentation will output to the build directory.

Build the Documentation Manually

Installing the needed Packages

To build the documentation you'll need to install dependencies using:

pip install -r requirements.txt

To run the pip command, python-pip package must be previously installed.

Building the Documentation

After installing the required packages, you can build the documentation using make.

Create all the HTML docs. Including all the languages:

make html

Create just the English HTML docs:

make html-en

Create all the EPUB (e-book) docs:

make epub

Create just the English EPUB docs:

make epub-en

After making changes to the documentation, you can build the HTML version of the docs by using make html again. This will build only the HTML files that have had changes made to them.

Building the PDF

Building the PDF is a non-trivial task.

Install LaTeX - This varies by distribution/OS so refer to your package manager. You should install the full LaTeX package. The basic one requires any additional packages to be installed with tlmgr
Run make latex-en.
Run make pdf-en.

At this point the completed PDF should be in build/latex/en/CakePHPCookbook.pdf.

Contributing

There are currently a number of outstanding issues that need to be addressed. We've tried to flag these with .. todo:: where possible. To see all the outstanding todo's add the following to your config/all.py

todo_include_todos = True

After rebuilding the HTML content, you should see a list of existing todo items at the bottom of the table of contents.

You are also welcome to make and suggestions for new content as commits in a GitHub fork. Please make any totally new sections in a separate branch. This makes changes far easier to integrate later on.

Translations

Contributing translations requires that you make a new directory using the two letter name for your language. As content is translated, directories mirroring the English content should be created with localized content. For more info, please, click here.

Making Search Work Locally

Install elasticsearch. This varies based on your platform, but most package managers have a package for it.
Clone the docs_search into a web accessible directory.
Modify searchUrl in themes/cakephp/static/app.js to point at the baseurl for your docs_search clone.
Start elasticsearch with the default configuration.
Populate the search using tooling found in the cakephp docs builder project.
You should now be able to search the docs using elasticsearch.

docs's People

Contributors

Stargazers

Watchers

Forkers

evilbloodydemon huoxito carlmuluba jrbasso asecondwill pjosephson steinkel simkimsia jszoja montblanc-sucks hiromi2424 robisonkarls petteyg kriskhaira 0x20h ajibarra suzuki pushnell majna shama jocull jamiemill kouno imsamurai mundosica a10801973 carolinekeyla rchavik brunosinister sartun toomuchcaffeine michaelkuhinica bsdis soulriser tdoi tlatsas wolg teddyzeenny cincodenada ryoabe ionas silwing webtechnick tigrang cdvrooman luchomolina rabidfire zoghal nojimage overflow636 mutz nullaware mhamann wa0x6e kleberhs007 lizaifang mathop dall rustyweb unikapps sime yandod gkalim vitorpacheco dakota yeliparra maurymmarques vtek21 dype35 ramonakira botcheddevil kewinwang erickbelfy amjithps dkullmann okonomi maff- thicolares potix2 sarahhenkens nicholasareed josselinh vodd m-arimoto pmanolak abhijatyatewari paznos ataylor32 robations iwat volponi angelxmoreno mikeboehm vinhboy azur29 tbsmcd shin1x1 msng ichikaway waterada

docs's Issues

Lighthouseapp ticket #117: Logging - unknown scope logs nowhere instead of everywhere

https://cakephp.lighthouseapp.com/projects/43067/tickets/117-logging-unknown-scope-logs-nowhere-instead-of-everywhere

http://book.cakephp.org/2.0/en/core-libraries/logging.html

says:

CakeLog::warning('this gets written to both shops.log and payments.log', 'unknown');

but this is wrong. Because it logs nowhere.
This is also written in the API docs in CakeLog::config():

All other scopes including the undefined scope will be ignored.

Open and close <?php ?> tags in tutorial

Ex: http://book.cakephp.org/2.0/en/tutorials-and-examples/blog/part-two.html

Might be less confusing for beginners.

Wrong search results

Searching the 2.x version includes results from 3.x.

The following returns incorrect results:
http://book.cakephp.org/2.0/en/search.html?q=Entity
http://book.cakephp.org/2.0/en/search.html?q=orm
http://book.cakephp.org/2.0/en/search.html?q=Eager

On a side note, the 'Improve this Doc' link shouldn't be visible.

3.0 - Explain how query formatters work

We have documentation for mapReduce, but not for formatResults, add some examples on how to formatResults for assciations too.

Lighthouseapp ticket #90: Cookbook PDF pt

https://cakephp.lighthouseapp.com/projects/43067/tickets/90-cookbook-pdf-pt

Hello, I can not download the cookbook pdf in Portuguese. Is offline.

I wish I had the cookbook printed.

http://book.cakephp.org/2.0/_downloads/pt/CakePHPCookbook.pdf

Character-Replacements in PDF-Version

Hi,

at least in the 2.0-PDF-Version of the cookbook ' are replaced with ´

Examples can be found at http://book.cakephp.org/2.0/_downloads/en/CakePHPCookbook.pdf

For example on page 11:
<td><?php echo $post[’Post’][’id’]; ?></td>

I don't know if this problem still exists in 3.0 or if it is more LATEX-related but at least for PHP-beginners this may cause confusion.

BR
Sven

Getting Started -> CakePHP Folder Structure: Double "webroot"

Hey there,
just checked out your new CakePHP 3.0 documentation and found something confusing at the Getting Started -> CakePHP Folder Structure page

There are two "webroot" which should both serve as the public document root?

Am I missing something there or is there really space for improvement here?

Thanks for reading
func0der :)

Create Serbian skeleton

I am wiling to translate docs to Serbian language.

Lighthouseapp ticket #98: Vendor docs

https://cakephp.lighthouseapp.com/projects/43067/tickets/98-vendor-docs

The ticket there contains a few comments.

The Vendor Packages page is pretty useless currently.

I think it should at least link to App - Loading Vendor Files

Or move the current docs there to Vendor Packages.

I don't think it would be at all obvious to someone new to Cake to look under the App Class to find out how to load 3rd party libraries the cake way.

3.0 - Document Collection::insert()

Check the class doc blocks and tests for examples

3.0 update docs for view cells

View cells have been merged onto 3.0. Update the docs. See cakephp/cakephp#3052

3.0 - Better description association aliases

Currently it is not clear that you can alias an association to any name by using the className key in the options array. Having an example with Parent - Child relationships for the same table could help

Add a "Improve this doc" button.

The Angularjs docs have an "Improve this doc" button at the top of each page which is simply a link to edit relevant page on github. If possible we too should add such a button. While having the links to doc repo in footer is nice having a more visible link/button at the top will hopefully encourage more contributions from the community for improving docs.

3.0 - Installing CakePHP with composer

Are we okay with simplifying the "Installing CakePHP with composer" section of the Advanced Installation docs to redirect the user to the cakephp/app repository and providing the instructions based on cakephp/app, rather than walking the user through how to set up a Composer JSON file and all that non-sense (which was really just required for 2.x)? If so, I'll draft this up.

3.0 - Update docs for multi operations in Cache

See cakephp/cakephp#3313 for the relevant code changes that need documentation.

3.0 - Ensure SQLServer support is in docs still

We should make sure SQLserver support is documented.

Lighthouseapp ticket #131: Update cookbook joins documentation

https://cakephp.lighthouseapp.com/projects/43067/tickets/131-Update-cookbook-joins-documentation

In the chapter Joining tables (http://book.cakephp.org/2.0/en/models/associations-linking-models-together.html) should be specified that fields for joined table needs to be specified.

Like this:

$var = $this->{$this->modelClass}->find('all', array("fields" => array('Table1.*','Table2.*','Table3.*') "joins" => $joins);

Here is a similar problem that I encountered when I added this ticket. Maybe this will help you because I don't remember when I needed to use this.
http://stackoverflow.com/questions/7443891/problem-with-cakephp-model-joins-missing-fields-from-joined-table

Keep the docs DRY

Sections are repeated in full. As a first time reader of the pdf my first impression was wow +1100 pages. But how many of those are repeated? +1100 pages is quite nuts.

Repeating sections also makes it hard to track what you have covered and what you haven't.

I'm not exactly sure how many sections are duplicated, but it looks significant.

This arrangement is an impediment to trying to understand Cake so I would like to put it forward that the documentation adopts the principal that sections obey a strict hierarchy, where there is exactly one path to each section.

Security::inactiveMins obsolete?

http://book.cakephp.org/2.0/en/core-utility-libraries/security.html#Security::inactiveMins

//If your config Security.level is set to 'medium' then $mins will equal 100

Since Security.level isn't used anymore, is this function still needed?

3.0 - Post master -> 3.0 merge fixes

Fix en/development/routing.rst array syntax errors starting at line 404 after master->3.0 merge.

Simple Acl controlled Application - part 2

For the part "Finally execute the following command in the CakePHP console:",

I suggest adding a Windows version of the command:

cake -app "C:\xampp\htdocs\Cake_2.4.1\app" AclExtras.AclExtras aco_sync

Find threaded in fields array required both field: id and parent_id

In description of find('threaded') http://book.cakephp.org/2.0/en/models/retrieving-your-data.html#find-threaded (red box) is wrote: when We want use fields clausule We must add to array field parent_id.

Now I use 2.4.3 and I must use both fields: id and parent_id. There is info only about parent_id. When my fields array will be without id, the results not nested.

3.0 - Getting started model relations

Just running through the Getting Started guide and there is nothing about relating models or displaying related model data.

Is this intentional to keep the guide simple? In which case I would recommend adding to the Suggested Follow-up Reading.

If it's just missing, then okay!

Lighthouseapp ticket #81: .method:hover .headerlink makes .method dt 1px larger

https://cakephp.lighthouseapp.com/projects/43067/tickets/81-methodhover-headerlink-makes-method-dt-1px-larger

The ticket there contains several comments.

When hovering a dl.method, a.headerlink that shows a paragraph-sign goes from display:none to display:inline. When it becomes visible, the parent of the link, a dt, becomes 1px higher than before causing it to "flicker". This happens in all browser I've tested: FF10, C17.

Lighthouseapp ticket #137: URL Rewriting appears three times in the index

https://cakephp.lighthouseapp.com/projects/43067/tickets/137-url-rewriting-appears-three-times-in-the-index

When you visit the cookbook and go to the url rewriting article, which I created a few weeks ago, then it appears three times in the index
http://book.cakephp.org/2.0/en/installation/url-rewriting.html

Installation

URL Rewriting (Where it really is)

Getting Started
2. URL Rewriting

Tutorials & Examples
Blog Tutorial
3. URL Rewriting

Not sure if it's a bug of the cookbook system or if i did something wrong back in my Pull Request #484

Lighthouseapp ticket #99: No datatype mapping information

https://cakephp.lighthouseapp.com/projects/43067/tickets/99-no-datatype-mapping-information

The ticket there contains a few comments.

For the 1.3 book, it is very useful knowing this information:
http://book.cakephp.org/1.3/en/The-Manual/Developing-with-CakePHP/Models.html#creating-database-tables

To know what database datatypes will work [best] in Cake.

However there is no such information for the 2.x book now that cake is using PDO.

Plugin AppController inheritance

I created a plugin and added an AppController that looked like this:

// Plugin/Templates/Controller/TemplatesAppController.php
<?php
App::uses('Controller', 'Controller');

class TemplatesAppController extends Controller {
    public function beforeFilter() {
    }
}

I didn't want the controller to inherit logic from app AppController so after a while I found I had to redefine $_mergeParent property.

Perhaps this is an edge case but I think this should be reflected in the documentation.

What do you think?

Lighthouseapp ticket #134: "Commenting Code" under Contributing Conventions is outdated

https://cakephp.lighthouseapp.com/projects/43067/tickets/134-commenting-code-under-contributing-conventions-are-outdated

I propose a rewrite of this http://book.cakephp.org/2.0/en/contributing/cakephp-coding-conventions.html#commenting-code section.

Because

the links refer to the old version of phpDocumentor
there is a new version of the docs for phpDocumentor2
CakePHP uses now ApiGen www.apigen.org which handles the tags differently
Some tags are never/very rarely used in the CakePHP code
Tags like @license are missing which are used heavily in the code

Personally I think we should not only state that those tags are possible but I think we should give contributors clear instructions what should and what not.

For example how should the PHP file header comment block look like?
Which phpdoc tags are allowed and where (mandatory, optional).
Show example of good practise etc.

If the CkaePHP core devs give me feedback what they want I will create a PR for the rewrite...

typo on the Table Objects ORM page

on this page http://book.cakephp.org/3.0/en/orm/table-objects.html we can read :

Assuming you have both the ‘published’ and ‘recent’ finders, you could do the following:

$articles = TableRegistry::get('Articles');
$query = $articles->find('publshed')->find('recent');

the code should be

$articles = TableRegistry::get('Articles');
$query = $articles->find('published')->find('recent');

Login/Logout issue

I have this problem in the Authorization part of the tutorial. http://book.cakephp.org/2.0/en/tutorials-and-examples/blog-auth-example/auth.html#authorization-who-s-allowed-to-access-what

// app/Controller/AppController.php

public $components = array(
    'Session',
    'Auth' => array(
        'loginRedirect' => array('controller' => 'posts', 'action' => 'index'),
        'logoutRedirect' => array('controller' => 'pages', 'action' => 'display', 'home'),
        'authorize' => array('Controller') // Added this line
    )
);

public function isAuthorized($user) {
    // Admin can access every action
    if (isset($user['role']) && $user['role'] === 'admin') {
        return true;
    }

    // Default deny
    return false;
}

If the user is of the "Author" type, it can't logout, and sometimes login.
Every time the user is trying to logout, the request is blocked in isAuthorized() function and the logout() function is never executed.
Similar thing happens with login(about every second time), login is not working.

What is the best way to fix this?

I managed to make it work, but it is probably not the right way:

public $components = array(
        'Session',
        'Auth' => array(
            'loginRedirect' => array('controller' => 'posts', 'action' => 'index'),
            'logoutRedirect' => array('controller' => 'users', 'action' => 'login'),
            'authorize' => array('Controller') // Added this line
        )
    );

    public function isAuthorized($user) {
        // Admin can access every action
        if (isset($user['role']) && $user['role'] === 'admin') {
            return true;
        } if (in_array($this->action, array('logout'))) {
            return true;
        }

        // Default deny
        return false;
    }

Added one 'if' statement in isAuthorized, and changed logoutRedirect to login action.

Broken installation link -- Get the "502 Bad Gateway" error

The Blog tutorial page (http://book.cakephp.org/1.3/en/The-Manual/Tutorials-Examples/Blog.html) contains a broken installation link under the http://book.cakephp.org/1.3/en/The-Manual/Tutorials-Examples/Blog.html#a-note-on-mod-rewrite section.

I think it should be pointing to http://book.cakephp.org/1.3/en/The-Manual/Developing-with-CakePHP/Installation.html

Please correct me if I'm wrong.

Lighthouseapp ticket #141: ePub document via Chrome on iPad/iPhone

https://cakephp.lighthouseapp.com/projects/43067/tickets/141-epub-document-via-chrome-on-ipadiphone

When attempting to open the epub file, as found at http://book.cakephp.org/2.0/en/index.html [direct link is http://book.cakephp.org/2.0/_downloads/en/CakePHPCookbook.epub] via Chrome on an iPad or iPhone, Chrome reports an error that is can not open the file due to an unknown file type.

When attempting to open the same file on a Google Nexus 7, via Chrome, the file is downloaded as plain text (although I don't have a proper eBook reader installed, except for Google Play Book, yet).

I'm wondering if this is because the web server has not been set up correctly, so that the epub extension is recognised and the appropriate mime type is sent.

Lighthouseapp ticket #139: Link to Contributors license agreement is broken

https://cakephp.lighthouseapp.com/projects/43067/tickets/139-link-to-contributors-license-agreement-is-broken

On cookbook page
http://book.cakephp.org/2.0/en/contributing/code.html

the link to the Contributors license agreement is broken:
http://cakefoundation.org/pages/cla

Unfortunately I haven't found the right one yet.

3.0 - Document find('threaded')

We missed explaining this method for 3.0

manual ebook on amazon request

Is there any chance to have calephp cookbook copy on amazon store? I need it to mantain notes/highlights after new manual versions.

If there is no plan for that may i put it on the store by myself? for free and with all the references to cakephp of course!

Missing link for 3.0 book in dropdown for version selection.

Book for 2.0 and below don't have link for switching to 3.0.

3.0 - Update docs for beforeFind

The event now gets a 4th argument, which means whether the event was fired for the main table in the query or for an association

CakePHP 1.3 - Using Containable

I am working on a project which is currently on CakePHP 1.3, looking the docs came across a small error, that I really thinks need to update (at least for newbie).

URL : http://book.cakephp.org/1.3/en/The-Manual/Core-Behaviors/Containable.html#using-containable-with-pagination

Line (that need to be updated) : See the section Using Containable for further details.

Text (that need to be updated) contains the wrong URL
Using Containable => http://book.cakephp.org/view/1324/Using-Containable

Please, updated the correct URL.

Create a Romanian documentation

I am willing to start and support a Romanian version of this document.

epub version of Cookbook doesn't match PDF and has bad links

The table of contents doesn't match the Feb 6, 2014 version of the PDF. There are also bad links in the ToC, namely the whole "Welcome" section. I just built the latest version from Git and the same issues exist so it seems something specific to the epub build file(s) need to be updated.

** This issue was originally opened under cakephp/cakephp as Issue #2790 but belongs here in the docs project. I'm closing out the other one in favor of this one.

I've already fixed this issue and others related to the epub build process and will submit a pull request soon (still learning how to use git & github).

3.0 Article model search entities table - based on blog tutorial

I try test new Cake 3.0 with docs.
But when I try build my first add/edit from echo $this->Form->create($article); it always looking for entities table by query: SHOW FULL COLUMNS FROM entities.
But I use articles table (based on tutorial: http://book.cakephp.org/3.0/en/getting-started.html#data-validation).

3.0 - Update TreeBehavior docs

The docs for TreeBehavior will need to be updated since it has been rebuilt for 3.0

Missing code

In the PDF version of the book, a lot of pages are missing code. For example: 17,18,62,67...

3.0 - Update shell docs for ConsoleIo

Update the docs for changes to Shell related to ConsoleIo. See cakephp/cakephp#3299

3.0 - Update docs inline with recent changes in cakephp/cakephp#2986

Refs cakephp/cakephp#2986. Not entirely sure what changes need to be made yet. Given setting view options directly on Controller was maintained, probably only minor updates needed.

Image link broken

An image link is broken at --> https://github.com/cakephp/docs/blob/master/en/getting-started/a-typical-cakephp-request.rst

3.0 - ORM Upgrade guide

Document: http://book.cakephp.org/3.0/en/appendices/orm-migration.html#inflection-rules-updated

Section:

Note
BelongsTo and HasOne associations will use the singular form, while HasMany and BelongsToMany (HABTM) will use plural forms.

This does not seem to be true.

I have setup Questions and Users

// QuestionsTable.php
$this->belongsTo('User');

// UsersTable.php
$this->hasMany('Questions');

$questions = $this->Questions->find()
    ->contain('User')
    ->order(['Questions.created' => 'DESC']);
// Errors with 'Questions is not associated with Users'

I've had to update my relationship to be $this->belongsTo('Users'); and my contain to ->contain('Users')

RFC - Usage of backticks

Throughout the documentation, the usage of backticks is very whimsical. It's very sporadic between object names, working directories, general highlighting/emphasis, code snippets, third party library names, etc. I think there should be a consistent distinction between italics, bolding, and backtick highlighting. While this may seem trivial, subconsciously it builds confidence in the reader while digesting information across different pieces of the documentation. For contributors, it may seem confusing on when to use backticks, bolding, or italics. Or for the contributor, perhaps -- "Am I overusing this?" That being said, I'm more than happy to take on this monotonous share of work if we come to a consensus.

As a starting point for discussion, I'll propose:

Backticks
Object names, excluding the following word "object"
Method/function names -- include "()"
Inline PHP, HTML SQL, etc

Bold
Working directories
Bullet list subject
Table names, excluding the following word "table"

Italics
General highlighting/emphasis
Names of method options
Names of table columns

Changes in CakePHP Cookbook

Just going through the Cookbook. the method to find server name given in page 10 under tmp dir permissions is
but i think it should be
thank u.

Lighthouseapp ticket #138: Cookbook mentions deprecated paginate in several places

https://cakephp.lighthouseapp.com/projects/43067/tickets/138-cookbook-mentions-deprecated-paginate-in-several-places

Controller::paginate() is deprecated:
https://github.com/cakephp/cakephp/blob/master/lib/Cake/Controller/Controller.php#L1071

But it is used in several places in the Cookbook:
http://book.cakephp.org/2.0/en/controllers.html#Controller::paginate
https://cakephp.lighthouseapp.com/projects/43067/tickets/138-cookbook-mentions-deprecated-paginate-in-several-places
Use of $paginate instead of $this->Paginator->settings
Use of $this->paginate() instead of $this->Paginator->paginate()

This goes alongside with:
https://cakephp.lighthouseapp.com/projects/42648/tickets/3895-baking-a-controller-uses-deprecated-paginate-et-al