Table

BC methods and properties

By using the Shim plugin Table class you can instantly re-use some 2.x behaviors. This is super useful when upgrading a very large codebase and you first need to get it running again, and afterwards want to start refactoring.

By default it will look if it can re-use the following (if not, nothing bad happens):

• $primaryKey
• $displayField
• $order (also with correct auto-aliasing; also works inside contain)
• $validate (needs minor adjustments)
• $actsAs
• all relations ($belongsTo, $hasMany, ...), as it would be very time-consuming to manually adjust all those

Also:

• Table::field() support and a fieldByConditions() alias to migrate to.

It automatically attaches the core Timestamp behavior, which updates created and modified columns when present. To disable automatic attachment, set both $this->createdField and $this->modifiedField to false before calling parent::initialize(). For custom timestamp columns, add Timestamp yourself with its events configuration before calling the parent.

IN / NOT IN

These were quite handy in 2.x: any 'field' => $values would be automatically converted. This was removed in 3.x and you manually have to decide if you need to add IN/NOT IN. When upgrading from 2.x, the following snippets can help ease migration (especially if the counterpart has been applied to 2.x already):

// In Table class
$query = $this->find();

// This modifies the query right away
$query->where($this->arrayCondition($query, 'field', $values));

// You can also use the 2.x array shim, which returns an array
$query->where($this->arrayConditionArray('field', $values));

It also makes the statement more correct in general: IN [] matches nothing, while NOT IN [] matches every row, but the 2.x API so far used IS NULL, which could falsely match nullish records. The main reason this is also useful for 3.x is the hidden time-bomb in the ORM when an array can become empty and an exception is thrown.

Use with care

This shimmed functionality, and NOT clauses with deleting records, can be dangerous and in some cases lead to accidental truncation of tables if not carefully applied. In most cases you would not want the sudden empty-array exception, though, so either add manual non-empty checks or use this functionality only when you are sure it is safe.

Saving multiple entities

Core saveMany() is transactional by default and returns false if a save fails. Use saveManyOrFail() to throw an exception on failure:

$articles->saveManyOrFail($entities);

Shim's legacy saveAll() saves each entity separately and returns a combined boolean result. Use core saveMany() for new code.

Extending the Table class

Extend the Shim plugin Table class to get the functionality:

namespace App\Model\Table;

use Shim\Model\Table\Table as Table;

/**
 * App\Model\Table\MyTable class
 */
class MyTable extends Table {
}

In case you are using an app Table class yourself, you can just make that one extend the Shim plugin Table class:

namespace App\Model\Table;

use Shim\Model\Table\Table as ShimTable;

/**
 * App\Model\Table\Table class
 */
class Table extends ShimTable {
}

And then all your tables can extend your own app Table class:

namespace App\Model\Table;

/**
 * App\Model\Table\MyTable class
 */
class MyTable extends Table {
}