Соглашения (конвенции) в CakePHP



Сразу хочу подчеркнуть, что использование соглашений CakePHP хоть и является мощнейшим инструментом, облегчающим разработку, совсем не является обязательным условием, а носит рекомендательный характер. Вы всегда можете отказаться от их использования.

Соглашения в контроллерах (Controller Conventions)

Имена классов контроллеров указываются во множественном числе и имеют вид CamelCased, заканчиваться имена должны на Controller. UsersController и ArticleCategoriesController являются примерами обычных имен контроллеров.

Public методы в контроллерах представляют собой экшены (actions) доступ к которым может осуществляться через веб-браузер. Например запрос /users/view обратиться к методу view() контроллера UsersController. Методы protected или private доступа, через указание маршрута в адресной строке браузера, не имеют.

URL соображения относительно имен контроллеров

Как вы только что видели, одиночные названия, представляют доступ к контроллеру по простому строчному URL адресу. Например, UsersController (который будет определен в имени файла UsersController.php) будет доступен по адресу http://sitename.loc/users (URL адрес вашего сайта на локальном сервере).

В то же время вы можете использовать маршрут, в котором названия состоят из нескольких слов. Тогда, согласно соглашению, URL-адреса должны указываться в нижнем регистре через дефис (например /article-categories/view-all) . Такие действия, так же, являются корректными, запрос будет обработан с помощью класса DashedRoute и обратится к экшену viewAll(), контроллера ArticleCategoriesController.

При создании ссылки с помощью Html хелпера this->Html->link(), вы можете использовать следующие условные обозначения в массиве формирования URL адреса:

echo $this->Html->link('link-title', [
    'prefix' => 'MyPrefix', // CamelCased
    'plugin' => 'MyPlugin', // CamelCased
    'controller' => 'ControllerName', // CamelCased
    'action' => 'actionName' // camelBacked
]);

Соглашения для названий файлов и классов

В большинстве случаев, имена файлов совпадают с именами классов, следуя стандартам PSR-0 или PSR-4 для автозагрузки. Ниже приведены некоторые примеры имен классов и имена файлов, в которых они находятся:

  • Класс контроллера LatestArticlesController будет найден в файле с именем LatestArticlesController.php;
  • Класс компонента контроллера MyHandyComponent будет найден в файле с именем MyHandyComponent.php;
  • Класс таблицы базы данных OptionValuesTable будет найден в файле с именем OptionValuesTable.php;
  • Класс объекта (модели) таблицы базы данных OptionValue будет найден в файле с именем OptionValue.php;
  • Класс поведения моделей EspeciallyFunkableBehavior будет найден в файле с именем EspeciallyFunkableBehavior.php;
  • Класс вида SuperSimpleView будет найден в файле с именем SuperSimpleView.php;
  • Класс хелпера вида BestEverHelper будет найден в файле с именем BestEverHelper.php;

Каждый файл должен находиться в соответствующей папке (пространстве имен) в структуре вашего приложения.

Соглашения в моделях и базах данных

Классы таблиц базы данных (классы моделей) должны иметь вид CamelCased и быть во множественном числе. Users, ArticleCategories и UserFavoritePages являются примерами названий таких классов.

Имена таблиц базы данных, соответствующих моделям в CakePHP должны быть во множественном числе. Если имя состоит из нескольких слов, то для их разделения используется нижнее подчеркивание. Основополагающие таблицы для вышеупомянутых моделей будут называться users, article_categories и user_favorite_pages, соответственно.

Так же вы должны помнить, что бы CakePHP правильно обрабатывал переходы от единственного числа ко множественному и наоборот, имена таблиц и столбцов должны быть на английском языке. Если вам нужно добавить свои собственные правила языка для некоторых названий, вы можете использовать утилиту класса Cake\Utility\Inflector. Помимо определения этих пользовательских правил класс Inflector, также позволяет проверить, как CakePHP понимает ваш пользовательский синтаксис для множественного или единственного числа используемых в названиях слов.

Внешние ключи в связях hasMany (один ко многим), belongsTo (многие к одному) / hasOne (один к одному) распознаются по умолчанию в качестве имени соответствующей таблицы (в единственном числе) с последующим: _id. Так что если пользователи связаны со статьями hasMany (один ко многим), то таблица articles будет относиться к таблице users с помощью внешнего ключа user_id. Если таблица содержит в названии несколько слов, например article_category_id, то внешний ключ будет article_category_id.

Связывающие таблицы, используемые в BelongsToMany (многие ко многим) отношениях между моделями, должны быть названы после создания таблиц моделей. Имя связывающей таблицы обязано содержать в себе имена таблиц моделей, расположенных в алфавитном порядке и разделенными нижним подчеркиванием (например articles_tags, а не tags_articles).

Так же, помимо использования ключа автоинкрементная в качестве первичного, вы можете использовать UUID столбцы. В этом случае CakePHP создаст уникальный 36 символьный ключ с помощью UUID метода (Cake\Utility\Text::UUID()) при сохранении новой записи в таблице (метод Table::save()).

Соглашения в видах (View)

Файлы шаблонов видов называются исходя из названий функций (экшенов) контроллера, которые они призваны представлять. Слова в названии файлов разделяются нижним тире. Например, функция viewAll() класса ArticlesController будет искать шаблон в файле src/Template/Articles/view_all.ctp.

Называя рабочие файлы своего приложения основываясь на CakePHP конвенции, вы получаете функциональность без особых хлопот и дополнительного обслуживания фалов конфигурации. Ниже представлен последний пример, который связывает конвенции вместе:

  • Таблица базы данных: «articles»;
  • Класс таблицы базы данных: ArticlesTable, будет искаться в файле src/Model/Table/ArticlesTable.php;
  • Класс объекта таблицы базы данных Article будет искаться в файле src/Model/Entity/Article.php;
  • Класс контроллера: ArticlesController, будет искаться в файле src/Controller/ArticlesController.php;
  • Шаблон вида будет искаться в файле src/Template/Articles/index.ctp;

При использовании соглашений, указанных в примере выше, CakePHP будет знать, что запрос http://yousite.ru/articles/ вызовет функцию index() класса ArticlesController, где модели Articles будут автоматически доступны (и автоматически привязаны к таблице «articles» базы данных), как и файл представления (src/Template/Articles/index.ctp). Ни одно из этих отношений не было настроено, просто были созданы необходимые классы и файлы, которые должны создаваться в любом случае.