3.4 Migration Guide¶

Request & Response Deprecations¶

The bulk of deprecations for 3.4 are in the Request and Response objects. The existing methods that modify objects in-place are now deprecated, and superseded by methods that follow the immutable object patterns described in the PSR-7 standard.

Several properties on Cake\Network\Request have been deprecated:

• Request::$params is deprecated. Use Request::getAttribute('params') instead.

• Request::$data is deprecated. Use Request::getData() instead.

• Request::$query is deprecated. Use Request::getQueryParams() instead.

• Request::$cookies is deprecated. Use Request::getCookie() instead.

• Request::$base is deprecated. Use Request::getAttribute('base') instead.

• Request::$webroot is deprecated. Use Request::getAttribute('webroot') instead.

• Request::$here is deprecated. Use Request::getAttribute('here') instead.

• Request::$_session was renamed to Request::$session.

A number of methods on Cake\Network\Request have been deprecated:

• __get() & __isset() methods are deprecated. Use getParam() instead.

• method() is deprecated. Use getMethod() instead.

• setInput() is deprecated. Use withBody() instead.

• The ArrayAccess methods have all been deprecated.

• Request::param() is deprecated. Use Request::getParam() instead.

• Request::data() is deprecated. Use Request::getData() instead.

• Request::query() is deprecated. Use Request::getQuery() instead.

• Request::cookie() is deprecated. Use Request::getCookie() instead.

Several methods on Cake\Network\Response have been deprecated because they either overlap the PSR-7 methods, or are made obsolete by the PSR-7 stack:

• Response::header() is deprecated. Use getHeaderLine(), hasHeader() or Response::getHeader() instead.

• Response::body() is deprecated. Use Response::withBody() instead.

• Response::statusCode() is deprecated. Use Response::getStatusCode() instead.

• Response::httpCodes() This method should no longer be used. CakePHP now supports all standards recommended status codes.

• Response::protocol() is deprecated. Use Response::getProtocolVersion() instead.

• send(), sendHeaders(), _sendHeader(), _sendContent(), _setCookies(), _setContentType(), and stop() are deprecated and made obsolete by the PSR-7 HTTP stack.

With responses heading towards immutable object patterns as recommended by the PSR-7 standards, a number of ‘helper’ methods in Response have been deprecated and immutable variants are now recommended:

• Response::location() would become Response::withLocation()

• Response::disableCache() would become Response::withDisabledCache()

• Response::type() would become Response::withType()

• Response::charset() would become Response::withCharset()

• Response::cache() would become Response::withCache()

• Response::modified() would become Response::withModified()

• Response::expires() would become Response::withExpires()

• Response::sharable() would become Response::withSharable()

• Response::maxAge() would become Response::withMaxAge()

• Response::vary() would become Response::withVary()

• Response::etag() would become Response::withEtag()

• Response::compress() would become Response::withCompression()

• Response::length() would become Response::withLength()

• Response::mustRevalidate() would become Response::withMustRevalidate()

• Response::notModified() would become Response::withNotModified()

• Response::cookie() would become Response::withCookie()

• Response::file() would become Response::withFile()

• Response::download() would become Response::withDownload()

Please see the Adopting Immutable Responses section for more information before updating your code as using responses through the immutable methods will require additional changes.

Other Deprecations¶

• The public properties on Cake\Event\Event are deprecated, new methods have been added to read/write the relevant properties.

• Event::name() is deprecated. Use Event::getName() instead.

• Event::subject() is deprecated. Use Event::getSubject() instead.

• Event::result() is deprecated. Use Event::getResult() instead.

• Event::data() is deprecated. Use Event::getData() instead.

• The Auth.redirect session variable is no longer used. Instead a query string parameter is used to store the redirect URL. This has the additional effect of removing the ability to store a redirect URL in the session outside of login scenarios.

• AuthComponent no longer stores redirect URLs when the unauthorized URL is not a GET action.

• The ajaxLogin option for AuthComponent is deprecated. You should use the 403 status code to trigger the correct behavior in clientside code now.

• The beforeRedirect method of RequestHandlerComponent is now deprecated.

• The 306 status code in Cake\Network\Response is now deprecated and has its status phrase changed to ‘Unused’ as this status code is non-standard.

• Cake\Database\Schema\Table has been renamed to Cake\Database\Schema\TableSchema. The previous name was confusing to a number of users.

• The fieldList option for Cake\ORM\Table::newEntity() and patchEntity() has been renamed to fields to be more consistent with other parts of the ORM.

• Router::parse() is deprecated. Router::parseRequest() should be used instead as it accepts a request and gives more control/flexibility in handling incoming requests.

• Route::parse() is deprecated. Route::parseRequest() should be used instead as it accepts a request and gives more control/flexibility in handling incoming requests.

• FormHelper::input() is deprecated. Use FormHelper::control() instead.

• FormHelper::inputs() is deprecated. Use FormHelper::controls() instead.

• FormHelper::allInputs() is deprecated. Use FormHelper::allControls() instead.

• Mailer::layout() is deprecated. Use Mailer::setLayout() provided by Mailer::__call() instead.

Deprecated Combined Get/Set Methods¶

In the past CakePHP has leveraged ‘modal’ methods that provide both a get/set mode. These methods complicate IDE autocompletion and our ability to add stricter return types in the future. For these reasons, combined get/set methods are being split into separate get and set methods.

The following is a list of methods that are deprecated and replaced with getX() and setX() methods:

Cake\Core\InstanceConfigTrait

• config()

Cake\Core\StaticConfigTrait

• config()

• dsnClassMap()

Cake\Console\ConsoleOptionParser

• command()

• description()

• epilog()

Cake\Database\Connection

• driver()

• schemaCollection()

• useSavePoints() (now enableSavePoints()/isSavePointsEnabled())

Cake\Database\Driver

• autoQuoting (now enableAutoQuoting()/isAutoQuotingEnabled())

Cake\Database\Expression\FunctionExpression

• name()

Cake\Database\Expression\QueryExpression

• tieWith() (now setConjunction()/getConjunction())

Cake\Database\Expression\ValuesExpression

• columns()

• values()

• query()

Cake\Database\Query

• connection()

• selectTypeMap()

• bufferResults() (now enableBufferedResults()/isBufferedResultsEnabled())

Cake\Database\Schema\CachedCollection

• cacheMetadata()

Cake\Database\Schema\TableSchema

• options()

• temporary() (now setTemporary()/isTemporary())

Cake\Database\TypeMap

• defaults()

• types()

Cake\Database\TypeMapTrait

• typeMap()

• defaultTypes()

Cake\ORM\Association

• name()

• cascadeCallbacks()

• source()

• target()

• conditions()

• bindingKey()

• foreignKey()

• dependent()

• joinType()

• property()

• strategy()

• finder()

Cake\ORM\Association\BelongsToMany

• targetForeignKey()

• saveStrategy()

• conditions()

Cake\ORM\Association\HasMany

• saveStrategy()

• foreignKey()

• sort()

Cake\ORM\Association\HasOne

• foreignKey()

Cake\ORM\EagerLoadable

• config()

• setter part of canBeJoined() (now setCanBeJoined())

Cake\ORM\EagerLoader

• matching() (getMatching() will have to be called after setMatching() to keep the old behavior)

• autoFields() (now enableAutoFields()/isAutoFieldsEnabled())

Cake\ORM\Locator\TableLocator

• config()

Cake\ORM\Query

• eagerLoader()

• hydrate() (now enableHydration()/isHydrationEnabled())

• autoFields() (now enableAutoFields()/isAutoFieldsEnabled())

Cake\ORM\Table

• table()

• alias()

• registryAlias()

• connection()

• schema()

• primaryKey()

• displayField()

• entityClass()

Cake\Mailer\Email

• from()

• sender()

• replyTo()

• readReceipt()

• returnPath()

• to()

• cc()

• bcc()

• charset()

• headerCharset()

• emailPattern()

• subject()

• template() (now setTemplate()/getTemplate() and setLayout()/getLayout())

• viewRender() (now setViewRenderer()/getViewRenderer())

• viewVars()

• theme()

• helpers()

• emailFormat()

• transport()

• messageId()

• domain()

• attachments()

• configTransport()

• profile()

Cake\Validation\Validator

• provider()

Cake\View\StringTemplateTrait

• templates()

Cake\View\ViewBuilder

• templatePath()

• layoutPath()

• plugin()

• helpers()

• theme()

• template()

• layout()

• options()

• name()

• className()

• autoLayout() (now enableAutoLayout()/isAutoLayoutEnabled())

Component Migration Tips¶

In previous versions of CakePHP, Components often held onto references to both the request and response, in order to make changes later. Before you adopt the immutable methods you should use the response attached to the Controller:

// In a component method (not a callback)
$this->response->header('X-Rate-Limit', $this->remaining);

// Should become
$controller = $this->getController();
$controller->response = $controller->response->withHeader('X-Rate-Limit', $this->remaining);

In component callbacks you can use the event object to access the response/controller:

public function beforeRender($event)
{
    $controller = $event->getSubject();
    $controller->response = $controller->response->withHeader('X-Teapot', 1);
}