cakephp / cakephp-api-docs

CakePHP API Docs

CakePHP is a rapid development framework for PHP which uses commonly known design patterns like Associative Data Mapping, Front Controller, and MVC. Our primary goal is to provide a structured framework that enables PHP users at all levels to rapidly develop robust web applications, without any loss to flexibility.

Installing CakePHP via Composer

You can install CakePHP into your project using Composer. If you're starting a new project, we recommend using the app skeleton as a starting point. For existing applications you can run the following:

composer require cakephp/cakephp

For details on the (minimum/maximum) PHP version see version map.

Running Tests

Assuming you have PHPUnit installed system wide using one of the methods stated here, you can run the tests for CakePHP by doing the following:

1. Copy phpunit.xml.dist to phpunit.xml.
2. Add the relevant database credentials to your phpunit.xml if you want to run tests against a non-SQLite datasource.
3. Run phpunit.

Some Handy Links

• CakePHP - The rapid development PHP framework.
• CookBook - The CakePHP user documentation; start learning here!
• API - A reference to CakePHP's classes.
• Awesome CakePHP - A list of featured resources around the framework.
• Plugins - A repository of extensions to the framework.
• The Bakery - Tips, tutorials and articles.
• Community Center - A source for everything community related.
• Training - Join a live session and get skilled with the framework.
• CakeFest - Don't miss our annual CakePHP conference.
• Cake Software Foundation - Promoting development related to CakePHP.

Get Support!

• Slack - Join us on Slack.
• Discord - Join us on Discord.
• #cakephp on irc.freenode.net - Come chat with us, we have cake.
• Forum - Official CakePHP forum.
• GitHub Issues - Got issues? Please tell us!
• Roadmaps - Want to contribute? Get involved!

Contributing

• CONTRIBUTING.md - Quick pointers for contributing to the CakePHP project.
• CookBook "Contributing" Section - Details about contributing to the project.

Security

If you’ve found a security issue in CakePHP, please use the procedure described in SECURITY.md.

cakephp-api-docs's Issues

Include the property listing *before* the method details

Move the property summary after the method summary but before the method details. This will help people who are trying to scan the property list without reading the full method docs.

sync footer

https://cakephp.org/

Templater docs are missing

Somehow the docs involving \Cake\View\StringTemplate and \CakeView\StringTemplateTrait are missing.

• http://api.cakephp.org/3.3/class-Cake.View.StringTemplate.html
• http://api.cakephp.org/3.3/class-Cake.View.StringTemplateTrait.html
• http://api.cakephp.org/3.3/class-Cake.View.Helper.HtmlHelper.html#_templater

There is no build-local for generating local changes

I might be missing something, but there wasn't a way to build using the source from my local cakephp branch. All of the targets will checkout a specific tag in SOURCE_DIR.

I also don't have a local environment to run make so I use Docker (similar to the use case in cakephp/docs).

I had to do 2 things to build locally:

1. Add a build-local target to Makefile
2. Create a barebones Dockerfile.dev that does not copy, build or run

How do you normally test your local source api doc changes?

HTML.Helper Doc is truncated for 3.0

The docs involving Cake\View\Helper\HtmlHelper is missing.

• http://api.cakephp.org/3.0/class-Cake.View.Helper.HtmlHelper.html

HtmlHelper::image() is not exist on API doc from 2.0 to 2.7

I find that HtmlHelper::image() is not exist on API doc from 2.0 to 2.7 when I maintain bit old website based on CakePHP 2.5.

https://api.cakephp.org/2.7/class-HtmlHelper.html#_image
https://api.cakephp.org/2.6/class-HtmlHelper.html#_image
https://api.cakephp.org/2.5/class-HtmlHelper.html#_image
https://api.cakephp.org/2.4/class-HtmlHelper.html#_image
https://api.cakephp.org/2.3/class-HtmlHelper.html#_image
https://api.cakephp.org/2.2/class-HtmlHelper.html#_image
https://api.cakephp.org/2.1/class-HtmlHelper.html#_image
https://api.cakephp.org/2.0/class-HtmlHelper.html#_image

Exists from 2.8

https://api.cakephp.org/2.8/class-HtmlHelper.html#_image

[mobile] Search results cut off

On (at least) chrome mobile the search results are cut off.

There should be a menu listing all plugins for which API docs are available.

Moving away from ApiGen?

As discussed in the dev channel :

• CakePHP uses ApiGen for generating its API documentations for years now
• ApiGen 4.x is not compatible with PHP 7.0+, usage of PHP 7 language features leads to "Unknown Token found." error
• ApiGen 5.x is not yet released, current release candidate seems to be a mess and general progress seems very slow
• CakePHP 4.0 will have a minimum PHP compatibility of 7+, so the current ApiGen will not work for us anymore

This means once we start working on CakePHP 4.0 we will not be able to generate API documentation anymore.

What are our options:

• Wait for ApiGen 5.0 to be released (may be help 'em)
• Moving away from ApiGen as our API docs generator

What alternatives are there?

• phpDocumentor2, the classic
• FriendsOfPHP SAMI, used by Symfony & Laravel
• calinrada/php-apidoc
• others?

Do not have a copy available to download, and view directly in HTML pages format

Issue:
I ( and maybe many people) want have a copy available in HTML format to download. I am a developer, but I try to folow instruction [1] to build document also very difficult. Many PHP web developers don't know how to use Make, Git, tools v.v..
Please build a copy available to download, and view directly. Save the time for everyone. Save the bandwidth for this link [2].

[1] https://github.com/cakephp/cakephp-api-docs
[2] http://api.cakephp.org/

Action: If you know how to build these API docs to HTML pages, create, zip, and put it to server to download directly. Thank you!

Update sponsor links/images

@markstory

We still have the old sponsors for api docs footer.

Add permalink icon to method details

The method summaries link to an anchor in the method detail. However, if you're just searching/scrolling through the details, you cannot generate a link to that method.

This is already possible with property details:

Missing packages/classes

The build of 2.3 API (didn't checked others) misses some packages/classes.
eg: Under App, there are no PagesController or AppController.

Checking the Makefile, seems like --exclude $(SOURCE_DIR)/lib/Cake/Console/Templates and/or --skip-doc-path $(SOURCE_DIR)/lib/Cake/Console/Templates prevent those packages/classes from being generated.

The HtmlHelper API Doc is not complete

The documentation
http://api.cakephp.org/3.2/class-Cake.View.Helper.HtmlHelper.html
is not complete.
It finishes with the css() method.

Links with text "link.link"

The link text is link.link instead of either the text given in the doc block or just the actual link. Probably an issue in the API docs generation?

https://api.cakephp.org/3.9/class-Cake.Http.Middleware.SecurityHeadersMiddleware.html#setReferrerPolicy

Turn on deprecated option in config

Having deprecated off in config is causing methods like View::element() to be not listed here http://api.cakephp.org/2.3/class-View.html. A quickfix would be to turn on the option until we can figure out a more optimal solution if any.

Broken .zip exports on api.cakephp.org

The ZIP exports on api.cakephp.org are broken. E.g.:
https://api.cakephp.org/3.3/CakePHP-API-documentation.zip (no docs inside; only resources/)

Menu links overflowing into body

When viewing the API (example page http://api.cakephp.org/3.2/class-Cake.Controller.Controller.html#_beforeRender). The menu links on the left (desktop view) are overflowing into the body of the document. This makes it very hard to read

Thanks

broken code formating in API Examples

From @Graziel on August 3, 2016 22:6

the code formating in Examples looks wierd (no intendation & new lines):
http://api.cakephp.org/3.2/class-Cake.ORM.Query.html#_leftJoinWith
vs
http://api.cakephp.org/3.2/source-class-Cake.ORM.Query.html#459-531

// Get the count of articles per user
$usersQuery ->select(['total_articles' => $query->func()->count('Articles.id')]) ->leftJoinWith('Articles') ->group(['Users.id']) ->autoFields(true);

vs

// Get the count of articles per user
$usersQuery
    ->select(['total_articles' => $query->func()->count('Articles.id')])
    ->leftJoinWith('Articles')
    ->group(['Users.id'])
    ->autoFields(true);

Copied from original issue: cakephp/docs#4227

I cant build the 3.0 api

I have tried to build the api 3.0 by follow the instructions given on the README.md, I've used the 3.0 branch of cakephp, but it doesn't generate it, though, I've executed

make build-all

and it has generated me the 2.0, ..., 2.4, and with

make build-3.0

I've got an error message saying

**make * Inexistant rules to make the target << build-3.0 >>. Stop

404 for Constants summary links

https://api.cakephp.org/3.5/class-Cake.ORM.Association.html#MANY_TO_MANY
click to one of link bellow the Constants summary
for example
https://api.cakephp.org/3.5/source-constant-MANY_TO_MANY.html#76-81

sync social block with main site

now

Can not see the document of version 1.1?

The following parts of the nginx.conf do not seem to work.

    location ~ ^/1\.1(.*)$ {
        return 301 http://api11.cakephp.org/;
    }

    location ~ ^/class/.*$ {
        return 301 http://api.cakephp.org/2.6$request_uri;
    }

• http://api11.cakephp.org/ -> After redirecting to https://api11.cakephp.org/ , you will see "Service Unavailable".
• https://api.cakephp.org/class/package-Cake.Cache.Engine.html -> After redirecting to https://api.cakephp.org/2.6/class/package-Cake.Cache.Engine.html, you will see "Not Found"

update favicons

sync wish main site

Layout: API Line Numbers show on top and are broken

Ref: http://api.cakephp.org/3.0/source-class-Cake.ORM.Table.html

update search bar on mobile

Hashtags in links to source code pages don't work

Eg. http://api.cakephp.org/2.4/source-class-Controller.html#311-343
Page doesn't scroll down to provide line numbers in hashtag like it does here http://cakephp-api.eu01.aws.af.cm/source-class-Controller.html#310-342

Layout: API should have syntax highlightning

From @ionas on July 4, 2016 14:37

See for example: http://api.cakephp.org/3.2/source-class-Cake.Validation.Validation.html#505
Unobtrusive, lazy/footer loaded through JS library if possible.

Copied from original issue: cakephp/docs#4149

Classes with non-Cake prefix are missing from sidebar class-nav

Applicable for versions < 3.0

Classes such as Controller, HtmlHelper, Datasource are not present in sidebar navigation.

Possible reason - inclusion of main: Cake in apigen.neon ?

fix navigation

big indents

Unable to easily copy permalink to class methods

With the methods summary removed for classes, it's no longer possible to easily copy the hashed link to a class method. It was handy to copy paste the link to newbies on IRC.

update social icon on mobile

add elastic search API to docs

also it would be great addition to add APIs of:

• elasticsearch
• bake
• acl

currently elastic search docs are not fully covered and many things can be found in only code

API Docs for 2.7 are not available

Even though CakePHP 2.7 has been released, there is no API docs for this version available at http://api.cakephp.org/2.7 as it is for 2.6 at http://api.cakephp.org/2.6

content goes off-screen

https://api.cakephp.org/4.2/class-Cake.Http.BaseApplication.html

add scroll to dropdown

Layout: API anchor links are hidden by static/fixed menu

From @ionas on July 4, 2016 14:35

http://api.cakephp.org/3.2/source-class-Cake.Validation.Validation.html#505 for instance is partially hidden at the top.

Copied from original issue: cakephp/docs#4148

Lesser than and Greater than rendering issues

I stumbled upon a rendering problem with < and > in the API doc. For instance :

http://api.cakephp.org/3.0/class-Cake.Validation.Validation.html#_comparison

The custom() method below has the problem too.
I can't tell if there is the problem in other Class / method however.

CakePHP API Docs Do Not Show Function Signatures On The Method Detail Portion

This is an issue with multiple versions of the API Docs:

1.3 API: http://api.cakephp.org/1.3/class-FileEngine.html#__setKey
2.0 API: http://api.cakephp.org/2.0/class-PhpReader.html#_read
3.0 API: http://api.cakephp.org/3.0/class-Cake.Core.Configure.html#_configured

All of those method definitions don't show any of the parameters for the function signature at the method detail point.

Asked @bcrowe about this and was told this was a bug and to report an issue as such.

Preceding dots missing for variadic args.

https://api.cakephp.org/4.0/class-Cake.Controller.Controller.html#setAction

$args is variadic param and should have ... in front.

Update chronos alias to point to 1.1

Function signature does not use docblock parameter types

If the parameter is missing a type, it shows mixed instead of using the doblock type.

Broken UI in Navbar second level - Documentation menu

http://api.cakephp.org/3.0/
The second level navbar appears broken for Documentation menu.

Trait methods that inheritDoc have no information

Many traits are used to implement an interface for a class. This means many methods have only @inheritDoc in the docblock.

When you look at the api docs for these traits, the methods all seem to be empty:

https://api.cakephp.org/4.2/trait-Cake.Collection.CollectionTrait.html#avg

Maybe we can add a note to methods in traits that are inheriting the docblocks. We won't be able to guess what interface they're implementing, but better than leaving all the return types as mixed.

@see does not generate link to reference class/method

The attributes section under the method in the class listing does not generate a link for the referenced method in from the @see tag.

https://api.cakephp.org/3.7/class-Cake.Console.CommandCollection.html#_addMany

See
\Cake\Console\CommandCollection::add()

api for new chronos

https://api.cakephp.org/chronos/1.1/

Method section doesn't show parameter datatypes

The "Method summary" shows datatypes for method parameters, see for example AuthComponent::initialize(): http://api.cakephp.org/2.0/class-AuthComponent.html

When you click on that to go to the detailed description of the method, you will see the parameters without the datatypes: http://api.cakephp.org/2.0/class-AuthComponent.html#_initialize

I wouldn't mind seeing the datatypes there as well.

Autocomplete is not generated for constants, methods, properties and classconstants

...it shows just classes and global functions

Version Picker/Dropdown has non ordered entries

Entry for version 2.7 appears before 2.8. It breaks the order in the dropdown.
Please find screen shot attached.

Non-overriden methods inherited from vendor classes generate wrong links

Methods that are purely inherited from a vendor class where they are not overridden generates the wrong link in method summaries.

https://api.cakephp.org/4.2/class-Cake.Http.Response.html

Here, Cake\Http\Response inherits withAddedHeader. The method details are generated, but the method summary links to:

https://api.cakephp.org/4.2/trait-Laminas.Diactoros.MessageTrait.html#withAddedHeader