- 1. toolkit
- 2. httpRequest
- 3. httpResponse
- 4. Routers
- 5. Resolver
- 6. arrayDataspace
Тулкит предназначен для того, чтобы получать необходимыe для работы экземпляры классов. Тулкит является реализацией The Composite Pattern и The Registry Pattern. И в свою очередь его можно назвать своеобразным глобальным хранилищем для различных объектов. В стандартной поставке в состав тулкита (конкретнее - класс stdToolkit) входят следующие методы:
- getRequest() - Возвращает объект httpRequest
- getResponse() - Возвращает объект httpResponse
- getSession() - Возвращает объект session
- getSmarty() - Возвращает объект mzzSmarty
- getRouter($request = null) - Возвращает объект requestRouter
- getConfig($section, $module) - Возвращает объект config
- getTimer() - Возвращает объект Timer
- getAction($module) - Возвращает объект Action для модуля $module
- getUser() - Возвращает объект текущего пользователя
- getObjectId($name = null) - Возвращает уникальный идентификатор необходимый для ACL (и "фейковых" объектов в частности)
- getMapper($module, $do, $section) - Возвращает необходимый маппер
- getCache() - Возвращает объект для работы с кэшем
- getValidator() - Возвращает текущий валидатор
- getController() - Возвращает контроллер действия модуля
- getLang() - Возвращает идентификатор текущего языка
- getLocale() - Возвращает объект текущей локали
- getSectionName() - Возвращает имя секции по имени модуля
- getModuleName() - Возвращает имя модуля по имени секции
- setRequest($request) - Устанавливает объект Request
- setResponse($response) - Устанавливает объект Response
- setSession($session) - Устанавливает объект Session
- setSmarty($smarty) - Устанавливает объект Smarty
- setRouter($router) - Устанавливает объект requestRouter
- setUser($user) - Устанавливает объект пользователя
- setConfig($config) - Устанавливает объект конфигурации
- setValidator($validator) - Устанавливает валидатор
- setLang() - Устанавливает идентификатор языка
- setLocale() - Устанавливает объект локали
Более подробную информацию о методах можно посмотреть в тестах, классе stdToolkit.
Для получения инстанции тулкита необходимо воспользоваться следующей конструкцией:
$toolkit = systemToolkit::getInstance();
К GET, POST, COOKIE и к параметрам в пути необходимо обращаться через класс httpRequest. В приложении существует только один объект этого класса, который может быть получен из Toolkit следующим образом:
$request = $toolkit->getRequest();
Для получения значения сушествует несколько методов, которые отличаются типом значения, которое будет получено из запроса.
<?php // Правило маршрутизации: :section/:action // URL: http://example.com/demo/view?show_execute_time=1 $request->getString('section'); // demo $request->getString('action', SC_PATH); // view $request->getBoolean('action', SC_PATH); // true $request->getBoolean('show_execute_time', SC_GET); // true ?>
Доступные методы:
| Имя | Описание |
| getString() | string (строка) |
| getInteger() | integer (целое число) |
| getNumeric() | numeric (любое число) |
| getArray() | array (массив) |
| getBoolean() | boolean (true или false) |
| getRaw() | любой тип (значение как есть) |
Если значение является массивом, а указанный тип не 'array', то из массива будет получен первый элемент, который и будет приведен к нужному типу. Если он тоже окажется массивом, результат будет null.
Каждый метод может принимать два аргумента: имя и источник данных. По умолчанию источник данных SC_PATH.
httpRequest может получать данные из следующих источников данных:
| Константа | Описание |
| SC_GET | массив $_GET (при GET-запросе) |
| SC_POST | массив $_POST (при POST-запросе) |
| SC_REQUEST | массив $_GET или $_POST (приоритет имеет $_POST) |
| SC_COOKIE | массив $_COOKIE |
| SC_SERVER | массив $_SERVER |
| SC_FILES | массив $_FILES |
| SC_PATH | результат обработки запрошенного пути объектом класса requestRouter |
Из объекта класса httpRequest могут быть получены такие данные, как: запрошенный URL, текущее действие, секция, принят ли запрос средствами AJAX и др. Описание всех методов можно найти в API-документации.
Класс httpResponse предназначен для хранения данных, отсылаемых клиенту в качестве ответа. К таким данным относятся куки, заголовки и непосредственно сам ответ. Отправка данных производится автоматически в конце, после выполнения всего кода.
Для установки кук используется метод setCookie(), с синтаксисом, сходным с синтаксисом нативной функции php setcookie. Типичный пример установки кук:
$response->setCookie('name', 'value', time() + 3600 * 24, '/');
В результате выполнения этого кода в куку с именем name установится значение value на 1 сутки и с доступом на весь текущий домен.
Отправка заголовков производится с помощью метода setHeader(). Первым аргументом идёт имя заголовка, вторым - значение. В случаях, когда заголовок не содержит как такового имени (например, статусный ответ 404), аргумент с именем следует оставить пустым или установить в null. Примеры:
$response->setHeader('', 'HTTP/1.x 404 Not Found'); $response->setHeader('Location', $url);
Для добавления к текущему ответу даных, используется метод append(). Его аргументом является строка, добавляемая к уже установленным данным. Для очистки ответа необходимо использовать метод clear().
$response->append('Sample response text');
Маршрутизация (Routing) - это процесс разделения запрошенного URL на ассоциативный массив с помощью правила (route) при совпадении пути из URL с ним. Правила маршрутизации хранятся в файле <project_folder>/configs/routes.php.
httpRequest с указанием в качестве второго аргумента SC_PATH.
Пример простейшего правила:
$router->addRoute('nameOfRule', new requestRoute('/ru/:section/:action'));
Перебор для поиска подходящего правил осуществляется в обратном порядке.
Где nameOfRule - уникальное имя для правила, /ru/:section/:action - шаблон. Шаблон может содержать разделитель / (прямой слэш), placeholder и raw-текст. В нашем примере :section и :action - placeholder, ru - raw-текст. Запрашиваемый URL example.com/ru/foo/bar совпадет с этим шаблоном и выполнится декомпозиция пути: в httpRequest будет помещен ассоциативный массив, где ключи - имена placeholder: section и action, значения - foo и bar соответственно. Raw-текст при этом сохранен не будет, он учитывается только в процессе проверки на совпадение.
Имя placeholder должно состоять только из латинских букв и знака подчеркивания ("_").
Таким образом в httpRequest будет помещен массив:
array([section] => foo, [action] = bar)
Любой placeholder может иметь значение по умолчанию, которые указываются во втором аргументе. Существовать этому placeholder в шаблоне необязательно (в примере ниже указано значение по умолчанию для placeholder-а id, но в самом шаблоне его нет).
$router->addRoute('nameOfRule', new requestRoute('/:section/:action', array('section' => 'news', 'action' => 'list', 'id' => 1)));
Данное правило совпадет со следующими URL: example.com/news/list, example.com/news, example.com, example.com/users, example.com/users/edit и т.п.
После декомпозиции в httpRequest будет помещен массив:
// example.com/news/list array([section] => news, [action] => list, [id] => 1) // example.com/news array([section] => news, [action] => list, [id] => 1) // example.com array([section] => news, [action] => list, [id] => 1) // example.com/users array([section] => users, [action] => list, [id] => 1) // example.com/users/edit array([section] => users, [action] => edit, [id] => 1)
По умолчанию границами для placeholder является разделитель / (прямой слэш). Вы можете это изменить, указав необходимое требование на языке perl-совместимых регулярных выражений (PCRE) в третьем аргументе:
$router->addRoute('nameOfRule', new requestRoute('/:section/:id-:action'), array(), array('id' => '\d+'));
Правило совпадет с URL example.com/news/1-view и в httpRequest будет помещено:
array([section] => news, [id] => 1, [action] => view)
Пример получения результата:
$section = $this->request->getString('section'); $id = $this->request->getInteger('id'); $action = $this->request->getString('action');
Резолверы предназначены для упрощения процесса подключения файлов. Резолверы возвращают полный путь к файлу (если он существует), часть которого передана в качестве единственного аргумента в методе resolve(). Например:
<?php $resolver->resolve('news'); // вернёт system/modules/news/news.php ?>
Композитный резолвер позволяет рассматривать группу резолверов как один. Таким образом, запрос будет передаваться каждому резолверу в группе, пока он не будет обработан кем-либо из них. Это позволяет реализовать поиск необходимых файлов в разных каталогах, либо когда в случае отсутствия (наличия) одного файла - нужно вернуть другой.
Пример создания и использования композитного резолвера:
<?php $compositeResolver = new compositeResolver(); $resolver1 = new firstResolver(); $resolver2 = new secondResolver(); $compositeResolver->addResolver($resolver1); $compositeResolver->addResolver($resolver2); $compositeResolver->resolve('file.php'); ?>
В этом примере файл file.php будет сначала передан в $resolver1. Если $resolver1 не сможет отрезолвить запрос, тогда запрос будет передан в $resolver2.
В приложениях, однако, обращаться напрямую к резолверам вам не придётся. Специально для непосредственной загрузки файлов предназначена обёртка для резолвера - fileLoader. В самом начале загрузки приложения составляется композитный резолвер, который будет резолвить все запросы поиска файлов. Затем этот резолвер передаётся в fileLoader, и затем при каждом запросе fileLoader::load, запрос будет делегироваться этому резолверу. Отметим также, что набор резолверов по умолчанию сделан таким образом, что для "подмены" любого оригинального файла из mzz, вам необходимо создать файл с таким же именем в каталоге www вашего проекта. (Например для подмены файла system/modules/news/controllers/newsSaveController.php, который отвечает за процесс отрисовки и обработки формы создания и редактирования новости - создайте файл www/modules/news/controllers/newsSaveController.php). Для вашего проекта это произойдёт прозрачно - никаких путей изменять не надо, за вас это сделают резолверы.
Не забудьте удалить файл resolver.cache, располагающийся в каталоге tmp вашего проекта, иначе будет использован кэш и может возвращаться неактуальная информация.
Пример создания резолвера и загрузки файлов с его помощью:
<?php $baseresolver = new compositeResolver(); $baseresolver->addResolver(new appFileResolver()); $baseresolver->addResolver(new sysFileResolver()); $resolver = new compositeResolver(); $resolver->addResolver(new classFileResolver($baseresolver)); $resolver->addResolver(new moduleResolver($baseresolver)); $resolver->addResolver(new configFileResolver($baseresolver)); $resolver->addResolver(new libResolver($baseresolver)); $cachingResolver = new cachingResolver($resolver); fileLoader::setResolver($cachingResolver); // установка резолвера fileLoader::load('exceptions/init'); // использование ?>
fileLoader работает аналогично управляющей структуре php require_once. Иными словами - fileLoader подключает файл только 1 раз.
arrayDataspace представляет собой реализацию инкапсулированного массива. Он предоставляет средства для установки, получения конкретных переменных, проверки на существование, экспорта/импорта всех данных, очистки. Датаспейс используется для внутреннего хранения данных, как альтернатива свойств классов.
<?php $item_one = "foo"; $item_two = "bar"; $dataspace->set('foo', $item_one); $dataspace->set('bar', $item_two); $dataspace->get('foo'); $dataspace->get('bar'); ?>