Lily Software

File System

Tue, 24 Oct 2023 18:38:00 +0300

Компонент для работы с файловыми хранилищами на основе Flysystem.
Он позволяет работать как с локальной файловой системой, так и с удаленными хранилищами используя единый интерфейс. Например с Amazon AWS S3, Azure Blob Storage, Yandex Objet Storage, BunnyCdn, Google Cloud Storage, WebDav, FTP, SFTP и др.

Класс для работы с локальной файловой системой входит в состав Cotonti Lib и не требует доплнительной установки других библиотек. Его интерфейс совместим с \League\Flysystem\FilesystemOperator и они взаимозаменяемы.

Для подключения другой (удаленной) файловой системы нужно установить Flysystem и нужный адаптер.

Для этого в composer.json нужно добавить строки:

"league/flysystem": "^3.0",
"league/flysystem-aws-s3-v3": "^3.0"

В этом примере мы добавили адаптер для файловых хранилищ, поддерживающий AWS S3.

И выполнить в командной строке:

composer update

Composer для Windows имеет баг который может в файле lib/composer/autoload_static.php сделать что то такое:

public static $fallbackDirsPsr4 = array (
  0 => 'C:\\OpenServerData\\domains\\my-site.loc\\public_html\\lib',
);

Надо вернуть как было:

public static $fallbackDirsPsr4 = array (
  0 => DIR . '/../..' . '/lib',
);

Теперь адатер файловой системы готов к использованию в коде Ваших расширений.

Для создания экземпляра можно воспользоваться инструкцией к соотвествующему адаптеру или воспользоваться "фабрикой" из Cotonti Lib.
Использование фабрики является предпочтительным при создании расширений т.к. позволяет конфигурировать подключения к файловым системам и использовать нужные в зависимости от конфигурации.

Конфигурирование файловых систем.

В файл datas/config.php нужно добавить элемент такого вида:

$cfg['filesystem'] = [
	
    // Подключение к Yandex Object Storage
    'Yandex.Cloud' => [
        'adapter' => '\League\Flysystem\AwsS3V3\AwsS3V3Adapter',
        'config' => [
            //'version' => 'latest', // Optional
            'endpoint' => 'https://storage.yandexcloud.net',
            'region' => 'ru-central1',
            'bucket' => 'my-bucket-name',
            'accessKey' => 'MyAccessKey',
            'secretKey' => 'MySecretKey',

            // install: composer require league/flysystem-path-prefixing:^3.3 to use prefix
            //'pathPrefix' => 'a/path/prefix',
        ],
    ],
	
    // Подключение к другому серверу по FTP
    'FTP' => [
        'adapter' => '\League\Flysystem\Ftp\FtpAdapter',
        'config' => [
            'client' => [
                'host' => 'my-pretty-host.tld',
                'root' => '/var/www/files/storage/here',
                'username' => 'server-user',
                'password' => 'someThingReallySecret',
            ],

            // install: composer require league/flysystem-path-prefixing:^3.3 to use prefix
            //'pathPrefix' => 'a/path/prefix',
        ],
    ],
	
    // Подключение к BunnyCDN
    'BunnyCDN' => [
        'adapter' => '\PlatformCommunity\Flysystem\BunnyCDN\BunnyCDNAdapter',
        'config' => [
            'storageZoneName' => 'test-files',
            'apiKey' => 'my-api-key',
            'pullZoneUrl' => 'https://test-files.b-cdn.net',
            //'region' => 'de', // optional

            // install composer require league/flysystem-path-prefixing:^3.3 to use prefix
            //'pathPrefix' => 'a/path/prefix',
        ],
    ],
];

В этом примере мы сконфигурировали подключение к Yandex Object Storage и к удаленному серверу по FTP.

Ключ массива - это название подключения, может быть любым.

'adapter' - имя класса адаптера. Поддерживаются и псевдонимы. Например вместо '\League\Flysystem\AwsS3V3\AwsS3V3Adapter' можно использовать 'Aws' или 'AwsS3'. Фабрика их поймет.

'config' - конфигурация подключения. Т.к. файловые системы имют очень разные API и способы подключения, то для каждого адаптера 'config' свой.
За подробностями можно обратиться к описанию самого адаптера и в код файла фабрики.

Если вы хотите добавить в фабрику подключение адаптера, которого в ней нет или создать подключение с более специфичной конфигурацией, то это можно сделать либо через хук filesystem.getFilesystem либо определив функцию cot_getFilesystem($fileSystemName, $pathPrefix).

Пример использования:

use \filesystem\FilesystemFactory;

// Получить экземпляр класса файловой системы по имени подлючения из конфига выше
$filesystem = FilesystemFactory::getFilesystem('Yandex.Cloud');

// Запись в файл
$filesystem->write($path, $contents);

Методы класса \League\Flysystem\Filesystem описаны в документации.

Image bundle

Tue, 24 Oct 2023 12:48:00 +0300

Компонент для работы с изображениями. Работает как с библиотекой GD, так и с ImageMagick. Последняя поддерживает большее количество форматов изображений, в т.ч. HEIC/HEIF, которые используются в смартфонах iPhone от Apple.

По умолчанию, если устанвлена ImageMagick, то используется она.

Чтобы использовать этот компонент в Ваших расширениях, добавте в начало php-файла

Получить используемый драйвер:

$driver = Image::currentDriver();

Метод возвращает одну из констант: Image::DRIVER_IMAGICK или Image::DRIVER_GD или null, если ни одна из библиотек недоступна и обработка изображений невозможна.

Получить список поддерживаемых форматов в виде массива:

$supportedFormats = Image::supportedFormats();

Загрузка изображения для дальнейшей обработки:

$image = Image::load($path, ?array $options = null);

в $path можно передать
- строку с путем к файлу или URL удаленного файла
- ресурс, полученный от fopen()
- строку с бинарными данными, содержащими избражение или строку закодированную в base64 c бинарными данными изображения
- data URL

в $options можно указать какой именно использовать, например:

$image = Image::load('/path/to/file', ['driver' => Image::DRIVER_GD]);

Этот метод возвращает экземпляр класса \image\imagick\Image или \image\gd\Image, которые являются наследниками класса \image\AbstractImage. Или будет выброшено исключение в случае неудачи.

Методы класса для работы с изображениями:

Можно получить экземпляр класса \Imagick или \GdImage|resource (в зависимости от используемой библиотеки) и работать с ними напрямую:

$image->getData();

Сохранить изображение:

$image->save(?string $fileName = null, ?int $quality = null, ?string $format = null);

$fileName - полный путь и имя файла для сохранения. Если не указано, то изменения будут сохранены в ранее загруженный файл. Иначе будет создан новый файл, а старый останется без изменений.

$quality - качество. Используется только если формат сохраняемого файла поддерживает этот параметр.

$format - формат сохраняемого изображения. Если не указано, будет использовано расширение файла.

Кодирование формата в указанный формат:

$image->encode(string $format, ?int $quality = null, ?string $fileName = null);

$format - формат изображения. Например: 'jpeg', 'png', 'heif'. Или 'data-url' для кодирования изображения в data Url;

$quality - качество. Используется только если формат сохраняемого файла поддерживает этот параметр.

$fileName - Имя файла для сохранения изображения. Если null - изображение будет возвращено в виде строки бинарных данных.

$image->crop(int $width, int $height, ?int $x = null, ?int $y = null);

Обрезает изображение.

Параметры $x и $y координаты правого верхнего угла области для нового изображения.

$width и $height - ширина и высота области нового изображения.

$image->fixOrientation();

Поворачивает изображение в соотвествии с данными об ориентации из EXIF

$image->flipHorizontally();
$image->flipVertically();

Отразить изображение горизонтально или вертикально соотвественно

$image->getWidth();
$image->getHeight();

Возвращают ширину и высоту изображения.

$image->getOrientation();

Возвращает ориентацию изображения из EXIF.

$image->paste(AbstractImage $image, $x, $y, $alpha = 100);

Вставляет одно изображение в другое. Может использоваться для наложения "водяного знака" или создания коллажей.

$image - вставляемое изображение. Экземпляр класса \image\imagick\Image или \image\gd\Image,

$x, $y - координаты левого верхнего угла вставляемого изображения

$alpha - прозрачность вставляемого изображения. 0 - полностью прозрачное. 100 - полностью непрозрачное.

$image->removeAnimation()

Удаление анимации. Gd и так не поддерживает анимацию. При использовании Imagick, в изображении будет оставлен только первый кадр.

$image->resize($width = null, $height = null, string $filter = Image::FILTER_UNDEFINED)

Изменение размера изображения.

$width, $height - новые ширина и высота изображения. Могут указываться как целое число в пикселях (1920) или процент ('80%'). Если ширина или высота не указана (null), то ее значение будет расчитано пропорционально.

$filter - фильтр применяемый для масштабирования. Одна из констант \image\Image::FILTER_XXX. GD не поддерживает фильтров и игнорирует этот параметер.

$image->rotate($angle, $background = null)

Поворачивает изображение на указанное количество градусов

$image->strip()

Удаляет EXIF данные из изображения. Gd удаляет эти данные в любом случае.

$image->thumbnail(
    $width, 
    $height, 
    string $resize = Image::THUMBNAIL_OUTBOUND, 
    bool $upscale = false, 
    string $filter = Image::FILTER_LANCZOS
)

Создает миниатюру изображения

$resize - как создавать миниатюру. Одна из констант:

\image\Image::THUMBNAIL_OUTBOUND - масштабирует изображение пропорционально таким образом, чтобы его ширина и высота были не меньшне указанных размеров. Если вторая сторона при этом превышает указанное значение - она обрезается.
\image\Image::THUMBNAIL_INSET - Исходное изображение масштабируется таким образом, чтобы оно полностью умещалось в размерах миниатюры (соотношение ширины и высоты изображения не меняется).
\image\Image::THUMBNAIL_HEIGHT - Миниатюра масштабируется так, чтобы ее высота равнялась желаемой высоте (соотношение ширины и высоты изображения не меняется).
\image\Image::THUMBNAIL_WIDTH - Миниатюра масштабируется так, чтобы ее ширина равнялась желаемой ширине (соотношение ширины и высоты изображения не меняется).

$upscale - увеливать изображение, если оно меньше указанных размеров.

Пример использования. Сделаем из исходного изображения миниатюру 160x160 и сохраним ее в формате jpeg:

$image = Image::load('/path/to/image.heic');

// Сделаем миниатюру
$image->thumbnail(160, 160, Image::THUMBNAIL_OUTBOUND);

// Сохраним в формате JPEG
$image->save('/path/to/image_160x160.jpg', 80);

// Выгрузим изображение из памяти:
unset($image);

View. PHP-шаблонизатор.

Sat, 13 Sep 2014 23:21:00 +0300

Исторически сложилось так, что Cotonti использует шаблонизатор CoTemplate, что накладывает значительные ограничения на возможности самих шаблонов, даже несмотря на то, что за последние годы он стал намного удобнее.

Но мы знаем, что PHP сконструирован специально для ведения Web-разработок и его код может внедряться непосредственно в HTML.
PHP — сам по себе является не только очень мощьным языком программирования, но и самодостаточным шаблонизатором, позволяющим делать качественные шаблоны без ущерба для логики приложения.

Такой стиль шаблонизации на PHP называют «pure-шаблонизация», т.е. чистая шаблонизация, основанная на возможностях самого PHP.

Класс View позволяет использовать шаблоны на чистом PHP.

Преимущества:

- Чистый PHP будет работать быстрее шаблонизаторов (интрепретаторов), написанных на PHP, т.к. нет программной "прослойки" между PHP и шаблоном, выполнение которой, как ни крути, а требует рессурсов. Хотя, многие современные шаблонизаторы компилируют шаблоны в PHP код.

- PHP и есть шаблонизатор и в шаблоне доступны все его возможности.

- Не нужно изучать дополнительный синтаксис. Знания HTML и шести - десяти конструкций на PHP вполне достаточно для верстки шаблона почти любой сложности.

Недостатки:

- Кто то считает, что «ужасный синтаксис». По-моему - это весьма субъективно и зависит от личных предпочтений. В моделях и контроллерах он уже не выглядит настолько ужасным )

- Слишком много лишнего текста в шаблонах. Тоже зависит от личных предпочтений и субъективно.

Итак к делу.

По существу применение View состоит из двух шагов:

1. Ваш скрипт контроллера создает экземпляр View и объявляет переменные этого экземпляра.

2. Контроллер приказывает View воспроизвести данный вид используя шаблон.

Скрипт контроллера

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

// Для наглядности, у нас есть массив с данными о книгах
$data = array(
	array(
	    'author' => 'Hernando de Soto',
	    'title' => 'The Mystery of Capitalism'
	),
	array(
	    'author' => 'Henry Hazlitt',
	    'title' => 'Economics in One Lesson'
	),
	array(
	    'author' => 'Milton Friedman',
	    'title' => 'Free to Choose'
	)
);

// теперь присваиваем данные по книгам экземпляру View
$view = new View();
$view->books = $data;

// и выполняем скрипт вида "booklist.php"
echo $view->render('library.booklist.php');

Скрипт шаблона:

Теперь нам нужен сопутствующий скрипт шаблона "library.booklist.php". Это такой же скрипт PHP, как и остальные, за одним исключением: он выполняется в области видимости экземпляра View, это означает, что $this ссылается на экземпляр View. Переменные, присваиваемые в контроллере для скрипта вида, являются открытыми свойствами экземпляра View. Таким образом, базовый скрипт вида может выглядеть следующим образом:

Список книг
books): ?>


books as $key => $val): ?>
    
    
        Author
        Title
    

    
        
        
    
    





Нет книг для отображения.

Класс View также подерживает присваивание переменных в стиле CoTemplate:

$view->assign(array(
    'PAGE_TITLE'  =>  $title,
    'BREADCRUMBS' =>  cot_breadcrumbs($crumbs, cot::$cfg['homebreadcrumb']),
));

что аналогично:

$view->PAGE_TITLE = $title;
$view->BREADCRUMBS = cot_breadcrumbs($crumbs, cot::$cfg['homebreadcrumb']);

Основные методы класса View:

render($viewFile, $type = 'module', $admin = null, $return = true)

Рендерит HTML код из шаблона и полученных данных.Принимает следующие параметры:

$viewFile - имя файла шаблона. Если не указано расширение или оно не входит в свойство класса $_extensions, будет использовано ".php".
$type - тип расширения. Может быть 'plug', 'module' or 'core'
$admin - использовать файл admin-темы, если возможно. По умолчанию эту опцию метод пытается определить исходя из параметра $viewFile
$return - Вернуть готовый HTML-код в виде строки (если TRUE) или выполнить require($viewFile)

Файл шаблона ищется по тем же правилам, что и при использовании функции cot_tplfile() для CoTemplate.

addScriptPath($path, $prepend = true)

Добавить дополнительный путь для поиска шаблонов.

$path - Путь к папке с шаблонами.
$prepend - Поместить путь в начало стека.

scriptFile($base, $type = 'module', $admin = null)

Ищет и возвращает полый путь к файлу шаблона или false, если шаблон не найден. Параметры аналогичны методу render();

SOM. (Simple Object Manipulation)

Tue, 13 May 2014 07:42:00 +0300

Общие сведения

SOM (Simple Object Manipulation) - это простая ORM, позволяющая работать с записями в базе данных посредством моделей, объектов, обладающих определенным набором методов, свойств и связями с другими моделями.

SOM является логическим продолжением ORM из cot-factory и представляет собой усовершенствованную и доработанную ORM из упомянутой библиотеки. Спасибо Gert Hengeveld и Владимиру Сибирову (trastmaster) за их труд над cot-factory.

Модели данных создаются в рамках паттерна MVC и соответствуют его концепции. Модели инкапсулируют основные операции с базой данных и позволяют абстрагироваться от непосредственной работы с ней и сосредоточится на программировании.

Требования

Для правильной работы необходим php не ниже версии 5.3

Использование нескольких соединений с бд

Иногда бывает необходимо использовать несколько соединений с базой данных. Например когда Вы используете данные, которые хранятся в разных БД или пишите конвертер для переноса данных из одной БД в другую. SOM предоставляет Вам такую возможность.

Для этого в файл datas/config.php вашего сайта добавте описание нужных соединений:

$cfg['db_connect_name'] = array(
      'adapter' => 'mysql',   // 'pgsql' or 'mongo'
      'host' => '127.0.0.1',
      'port' => null,
      'username' => '12345',
      'password' => '6789',
      'dbname' => 'my_data_base',
 );

Поддерживаются базы данных MySql и PostgreSQL. Mongo - эксперементально.

Чтобы установить соединение вызовите фабричный метод:

$db_my_conn = Som::getAdapter('db_connect_name');

который вернет объект Som_Model_Mapper нужного типа. После этого можно отправлять ему запросы обычным образом:

$db_my_conn->query("SELECT * FROM `cot_some_table` ORDER BY id ASC");

Также Вы можете передавать имена соединений моделям при инициализации, если необходимо использовать соединения, отличные от системного в Cotonti.

Соединения кешируются на период выполнения. Это значит, что Вы можете вызывать метод Som::getAdapter с одним и тем же параметром столько - сколько Вам нужно. Объект соединения с БД не будет создаваться каждый раз заново, а будет возвращаться ссылка на один раз созданный объект.

Создание моделей

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

protected static $_db;
protected static $_tbname = 'katalogshop_sale';

и опционально

protected static $_primary_key = 'prod_id';

$_db хранит ссылку на объект базы данных
$_tbname - имя таблицы в БД. Указывается явно при объявлении.
$_primary_key - название поля - первичный ключ таблицы. Если не указано, то используется поле 'id'.

В конце файла класса модели необходимо вызвать статический метод этого класса _init(). По умолчанию будет выполнен соотвествующий метод родительского класса. Это т.н. «статический конструктор», который выполняет начальную инициализацию модели, заполняет свойства $_db и загружает экстраполя.

пример модели расписания для группы ВУЗА:

_data['id']);
    }

    /**
     * @return bool
     */
    public function delete(){

        // Remove all files and images
        $files = files_model_File::find(array(
            array('file_source', 'sgrp_schedule'),
            array('file_item', $this->_data['id'])
        ));
        if(!empty($files)){
            foreach($files as $fileRow){
                $fileRow->delete();
            }
        }

         return parent::delete();
    }

    public static function fieldList() {
        return array(
            'id'  =>
                array(
                    'type'    => 'bigint',
                    'primary' => true,
                    'description' => 'id'
                ),
            'title'  =>
                array(
                    'type'      => 'varchar',
                    'length'    => '255',
                    'description' => 'Заголовок'
                ),
            'description'  =>
                array(
                    'type'      => 'varchar',
                    'nullable'  => true,
                    'default'   => '',
                    'length'    => '255',
                    'description' => 'Краткое описание'
                ),
            'text' =>
                array(
                    'type'      => 'text',
                    'nullable'  => true,
                    'default'   => '',
                    'description' => 'Текст'
                ),
            'begin'  =>
                array(
                    'type'      => 'datetime',
                    'default'   => date('Y-m-d H:i:s', cot::$sys['now']),
                    'description' => 'Дата начала'
                ),
            'end'  =>
                array(
                    'type'      => 'datetime',
                    'description' => 'Дата окончания'
                ),
            'created'  =>
                array(
                    'type'      => 'datetime',
                    'safe'      => true,
                    'description' => 'Дата создания'
                ),
            'created_by'  =>
                array(
                    'type'      => 'bigint',
                    'safe'      => true,
                    'description' => 'Кем создано'
                ),
            'updated'  =>
                array(
                    'type'      => 'datetime',
                    'safe'      => true,
                    'description' => 'Дата обновления'
                ),
            'updated_by'  =>
                array(
                    'type'      => 'bigint',
                    'safe'      => true,
                    'description' => 'Кем обновлено'
                ),
            'sgroup' =>
                array(
                    'type' => 'link',
                    'description' => 'Группа Вуза',
                    'link' =>
                        array(
                            'model'    => 'vuz_model_Group',
                            'relation' => Som::TO_ONE_NULL,
                            'label' => 'sgrp_title',
                        ),
                ),
        );
    }

    // === Методы для работы с шаблонами ===
    /**
     * Returns all Group tags for coTemplate
     *
     * @param vuz_model_Schedule|int $item vuz_model_Vuz object or ID
     * @param string $tagPrefix Prefix for tags
     * @param array $urlParams
     * @param int $textlength
     * @param bool $cacheitem Cache tags
     * @return array|void
     */
    public static function generateTags($item, $tagPrefix = '', $urlParams = array(), $textlength = 500, $cacheitem = true){

        static $extp_first = null, $extp_main = null;
        static $cacheArr = array();

        if (is_null($extp_first)){
            $extp_first = cot_getextplugins('vuz.schedule.tags.first');
            $extp_main  = cot_getextplugins('vuz.schedule.tags.main');
        }

        /* === Hook === */
        foreach ($extp_first as $pl){
            include $pl;
        }
        /* ===== */

        if(empty($urlParams)) $urlParams = array();
        if(empty($urlParams['m'])) $urlParams['m'] = 'group';
        if(empty($urlParams['a'])) $urlParams['a'] = 'schedule';

        if ( ($item instanceof vuz_model_Schedule) && is_array($cacheArr[$item->id]) ) {
            $temp_array = $cacheArr[$item->id];
        }elseif (is_int($item) && is_array($cacheArr[$item])){
            $temp_array = $cacheArr[$item];
        }else{
            if (is_int($item) && $item > 0){
                $item = vuz_model_Schedule::getById($item);
            }
            /** @var vuz_model_Schedule $item  */
            if ($item){

                // Права
                // Задание может править автор или староста
                $scheduleAuth['isadmin'] = cot_auth('vuz', 'a', 'A');
                if($scheduleAuth['isadmin']){
                    $scheduleAuth['auth_write'] = true;

                }elseif(cot::$usr['id'] == $item->created_by){
                    $scheduleAuth['auth_write'] = true;

                }else{
                    $grpAuth['isLeader'] = $item->sgroup->isLeader(cot::$usr);
                    if($grpAuth['isLeader']) $taskAuth['auth_write'] = true;

                }

                if(empty($urlParams['gid']) && !empty($grpIds)) $urlParams['gid'] = $item->sgroup->sgrp_id;
                $urlParams['sid'] = $item->id;

                $itemUrl = cot_url('vuz', $urlParams);
                $itemEditUrl = '';
                if($scheduleAuth['auth_write']){
                    $editUrlParams = $urlParams;
                    $editUrlParams['a'] = 'editSchedule';
                    $itemEditUrl = cot_url('vuz', $editUrlParams);
                }

                $itemDelUrl = '';
                if($scheduleAuth['auth_write']){
                    $editUrlParams = $urlParams;
                    $editUrlParams['a'] = 'deleteSchedule';
                    $itemDelUrl  = cot_confirm_url(cot_url('vuz', $editUrlParams),  'vuz', 'shedule_deleteConfirm');
                }

                $text = cot_parse($item->text);
                $text_cut = cot_cut_more($text);
                if ($textlength > 0 && mb_strlen($text_cut) > $textlength){
                    $text_cut = cot_string_truncate($text_cut, $textlength);
                }
                $cutted = (mb_strlen($text) > mb_strlen($text_cut)) ? true : false;

                $date_format = 'datetime_medium';
                $date_format = 'date_fulltext';
                $beginStamp = strtotime($item->begin);
                $endStamp = !empty($item->end) ? strtotime($item->end) : 0;
                $temp_array = array(
                    'URL' => $itemUrl,
                    'EDIT_URL' => $itemEditUrl,
                    'DELETE_URL' => $itemDelUrl,
                    'ID' => (int)$item->id,
                    'TITLE' => htmlspecialchars($item->TITLE),
                    'DISTPLAY_TITLE' => htmlspecialchars($item->displayTitle),
                    'DESC' => htmlspecialchars($item->description),
                    'BEGIN' => cot_date($date_format, $beginStamp),
                    'BEGIN_RAW' => $beginStamp,
                    'END' => cot_date($endStamp, $beginStamp),
                    'END_RAW' => $endStamp,
                    'TEXT' => $item->text,
                    'TEXT_CUT' => $text_cut,
                    'TEXT_IS_CUT' => $cutted,

                    'CREATED' => $item->created,
                    'CREATE_DATE' => cot_date($date_format, strtotime($item->created)),
                    'CREATED_RAW' => strtotime($item->created),

                    'UPDATED' => $item->updated,
                    'UPDATE_DATE' => cot_date($date_format, strtotime($item->updated)),
                    'UPDATED_RAW' => strtotime($item->updated),
                );

                /* === Hook === */
                foreach ($extp_main as $pl)
                {
                    include $pl;
                }
                /* ===== */
                $cacheitem && $cacheArr[$item->id] = $temp_array;
            }else{

            }
        }

        $return_array = array();
        foreach ($temp_array as $key => $val){
            $return_array[$tagPrefix . $key] = $val;
        }

        return $return_array;
    }

}

vuz_model_Schedule::__init();

Здесь очень важным является метод fieldList(), возвращающий массив с описанием полей в таблице. Обратите внимание на то, что модель не проверяет физическое наличие полей в таблице БД, а наивно доверяет возвращаемому массиву.
Ключом массива является имя поля, а значением массив с описанием в формате ключ=>значение и может содержать следующие данные:

'name' - название поля
'primary' - может быть только у одного поля. Значение true указывает на то, что поле явлается первичным ключом таблицы.
'type' - тип поля. Это SQL тип или 'link', если это поле является связью с другой моделью.
'length' - необязательно. Длина значения, например для varchar
'nullable' - необязательно. 'nullable' => false указывает на то, что поле не может принимать пустое значение.
'default' - необязательно. Значение по умолчанию. При создании нового экземпляра модели поле будет проинициализировано этим значением. Однако при получении существующего объекта, поле будет проинициализировано данными из БД.
'description' - необязательно. Описание поля.
'safe' - необязательно. Если TRUE , то поле является «защищенным» при заполнении модели данными методом setData(), при попытке заполнения этого поля выбросит исключение, если пользователь не является администратором или действие просходит не в панели управления.

Обращаться к полям модели можно как к обычным свойствам объекта.

Например:

$sсhedule = vuz_model_Schedule::getById(15);   // Получить существующий объект
$endStamp = !empty($sсhedule->end) ? strtotime($sсhedule->end) : 0;

Связи между моделями

Модель может содержать связи с другими моделями. Поддерживаются связи один-ко-многим и многие-ко-многим. Например, наше расписание принадлежит конкретной группе ВУЗ'а реализованной моделью vuz_model_Group. Эта связь описывается так:

'sgroup' =>
    array(
        'name' => 'sgroup',
        'type' => 'link',
        'description' => 'Группа Вуза',
        'link' =>
            array(
                'model'    => 'vuz_model_Group',
                'relation' => Som::TO_ONE_NULL,
                'label' => 'title',
            ),
        ),

Здесь в массив с описанием доля добавляется элемент 'link', описывающий связь:

'model' - имя класса связываемой модели
'relation' - тип связи. Возможные значения (константы класса Som):
    - Som::TO_ONE - один ко многим
    - Som::TO_ONE_NULL - один ко многим, разрешено пустое значение
    - Som::TO_MANY - многие ко многим
    - Som::TO_MANY_NULL - многие ко многим, разрешено пустое значение
'label' - необязательно. Свойство связываемого класса которое можно использовать для автоматического вывода связанных объектов. Напрмер 'title'.
'localkey' - необязательно. Имя поля в данной модели (а точнее в таблице БД), где хранится id связанного объекта. Используется только для связей один-ко-многим т.к. для хранения связей многие-ко-многим необходима отдельная таблица в БД, которая при необходимости создается автоматически.
Если параметр localkey не указан, то будет использовано само поле в котором описана связь. В данном случае - sgroup. Обратите внимание, что поле должно существовать в таблице в БД.

При обращении к полю связанному с другой моделью получим ссылку на объект этой модели. Например:

$prod = Product::getById(2);
echo $prod->topic->name; // Выведет поле name экземпляра класса «ProductTopic» (для один-ко-многим)

или

$prod = Product::getById(2);
// Это сработает, если у нас для поля $topics объявлена связь многие-ко-многим
foreach ($prod->topics as $topic){
    // do something ...
    echo $topic->name;
}

Запрос к базе данных на получение связанного объекта происходит только по необходимости. Т.е. в момент обращения

Полю со связью один-ко-многим можно присвоить id связанного объекта или сам объект

Например:

$prod = Product::getById(5);
$topic = ProductTopic::getById(2);

$prod->topic = 2;      // Присвоили id
$prod->topic = $topic; // Присвоили экземпляр класса ProductTopic(). По сути эти действия идентичны.

Присваивать можно либо самому объявленному полю, либо полю из БД, указанному в localkey

Присвоить можно только экземпляр того класса, каким объявлена связь.

Присваивание значений полям со связями многие-ко-многим аналогично с той разницей, что помимо id или самого объекта допускается присваивание содержащего их массива.

Основные методы класса Som_Model_Abstract

static _init($db = 'db')

Статический конструктор. Должен вызываться при включении файла конкретного класса модели. Выполняет начальную инициализацию модели, заполняет свойства $_db и $_columns. Он принимает один единственный необязательный параметр $db - тип базы данных, по-умолчанию используется соединение с БД Cotonti.

__construct($data = null)

Конструктор экземпляра. Автоматически вызывается при создании экземпляра модели.

Может принимать в качестве параметра другой экземпляр той же модели или массив (ключ-значение). В этом случае поля объекта будут инициализированы соответствующими значениями.

protected function afterDelete()

Выполняется после удаления объекта. По умолчанию метод ничего не делает, но Вы можете переопределить его для выполнения неких действий, спецефичных для Вашей модели.

protected function afterInsert()

Выполняется после добавления нового объекта в БД. По умолчанию метод ничего не делает, но Вы можете переопределить его для выполнения неких действий, спецефичных для Вашей модели.

protected function afterSave()

Выполняется после сохранения объекта независимо от того, есть соотвествующая запись в БД или нет. По умолчанию метод ничего не делает, но Вы можете переопределить его для выполнения неких действий, спецефичных для Вашей модели.

protected function afterSetData($data)

Выполняется после заполнения модели данными методом setData(); По умолчанию метод ничего не делает, но Вы можете переопределить его для выполнения неких действий, спецефичных для Вашей модели.

protected function afterUpdate()

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

protected function beforeDelete()

Выполняется перед удалением объекта. По умолчанию метод возвращает TRUE, но Вы можете переопределить его для выполнения неких действий, спецефичных для Вашей модели. Если метод вернет FALSE, удаление не произойдет и метод afterDelete() выполнен не будет.

protected function beforeInsert()

Выполняется перед сохранением нового объекта. По умолчанию метод возвращает TRUE, но Вы можете переопределить его для выполнения неких действий, спецефичных для Вашей модели. Если метод вернет FALSE, добавления объекта в БД не произойдет и метод afterInsert() выполнен не будет.

protected function beforeSave($data)

Выполняется перед сохранением объекта независимо от того, есть соотвествующая запись в БД или нет. По умолчанию метод возвращает TRUE, но Вы можете переопределить его для выполнения неких действий, спецефичных для Вашей модели. Если метод вернет FALSE, сохранение не произойдет и метод afterSave() выполнен не будет.

protected function beforeSetData($data)

Выполняется перед заполнением модели данными методом setData(); По умолчанию метод возвращает TRUE, но Вы можете переопределить его для выполнения неких действий, спецефичных для Вашей модели. Если метод вернет FALSE, заполнение данными не произойдет и метод afterSetData() выполнен не будет.

protected function beforeUpdate()

Выполняется перед сохранением существующего объекта. По умолчанию метод возвращает TRUE, но Вы можете переопределить его для выполнения неких действий, спецефичных для Вашей модели. Если метод вернет FALSE, сохранение объекта не произойдет и метод afterUpdate() выполнен не будет.

static count($conditions)

Возвращает количество элементов, соотвествующих условию, переданному в параметре $conditions

dec($pair = array(), $conditions = '')

Декремент. Уменьшает заданные поля на заданные значения. Запись в БД производится сразу при вызове метода.

delete()

Удалить данных объект из базы данных

protected static fetch($conditions = array(), $limit = 0, $offset = 0, $order = '')

Защищенный Метод. Он осуществляет выборку объектов из БД. Возвращает массив экземпляров класса, если объект существует или null если ничего не найдено. Публичные методы getById(), fetchOne() и find() являются по сути обертками для этого метода и делегируют запрос ему.

Хоть этот метод и нельзя вызвать извне, но его полезно переопределять для создания выборок, специфичных для конкретной модели. В этом случае методы getById(), fetchOne() и find() будут делегировать запрос переопределенному методу, даже если сами они и не переопределены.

static fetchOne($conditions, $order = null)

Получить объект по заданным условиям. Возвращает экземпляр класса, если объект существует или null в противном случае.

где:

$conditions - условия
$order - условие для сортировки - поле или поля чере запятую. В последнем случае для каждого поля можено указать порядок сортировки (ASC или DESC). Также может принимать массив условий, элементами которого являются массивы, ключи которых - поля, а значения - порядок сортировки.

Получаемый объект кешируется на время выполнения аналогично методу getById().

static find($conditions, $limit = 0, $offset = 0, $order = '')

Найти объекты по заданным условиям. Возвращает массив экземпляров класса, если объект существует или null если ничего не найдено.

где:

$conditions - условия
$limit - Количество выбираемых элементов
$offset - Смещение выборки от начально элемента
$order - условие для сортировки - поле или поля чере запятую. В последнем случае для каждого поля можено указать порядок сортировки (ASC или DESC). Также может принимать массив условий, элементами которого являются массивы, ключи которых - поля, а значения - порядок сортировки.

static getById($pk, $staticCache = true)

Получить объект по первичному ключу. Возвращает экземпляр класса, если объект существует или null в противном случае. Если параметр $staticCache - true, то результат работы кешируется на время жизни скрипта. Т.е. если для конкретной модели вызывать несколько раз этот метод с одним и тем же параметром, запрос к БД выполняется только один раз, потом возвращается ссылка на объект из кеша. При сохранении/удалении объекта кеш сбрасывается.

Кеширование нужно отключить, если используется несколько объектов с одним первичным ключом и разными наборами опций.

static getDbConfig()

Возвращает настройки БД для данного объекта в виде массива.

static fields()

Возвращает массив полей, описанных в модели, с типами данных и связей.

getId()

Возвращает значение первичного ключа объекта

getValidators($field = null)

Возвращает валидаторы для указанного поля объекта или все валидаторы объекта. Валидаторы используются для проверки данных объекта при его сохранении.

inc($pair = array(), $conditions = '')

Инкремент. Увеличивает заданные поля на заданные значения. Запись в БД производится сразу при вызове метода.

static primaryKey()

Возвращает название поля первичного ключа модели.

rawValue($column)

Возвращает значение поля $column «как есть». Никакие преобразования не производятся. Для связей "ко многим" связанные объекты из БД не выбираются, возвращается массив значений первичного ключа связанных объектов (массив их id)

save($data = null)

Сохранить текущий объект. качестве аргумента можно передать массив (ключ-значение). В этом случае перед сохранением поля объекта будут перезаписаны данными из массива.

setData($data, $safe=true)

Безопасное заполнение модели данными. Принимает следующие параметры:

$data - массив данных в формате имя_поля => значение. Например $_POST.
$safe - Если параметр установлен в TRUE и при этом действие происходит не в панели управления и пользователь не администратор ($usr['isadmin'] != TRUE), то при попытке передать в массиве $data имя_поля, которое в описании в моделе имеет элемент 'safe' => TRUE, будет выброшено исключение.

Данные при установке значений проходят проверку на соотвествие типам данных. Вам не нужно заботиться о рутинной проверке вводимых пользователями данных.

setValidator($field, $validators)

Устанавливает валидатор(ы) для заданного поля объекта

toArray()

Возвращает поля текущего объекта в виде массива.

static updateRows($data, $condition = '')

Обновить все записи в таблице, соотвествующие условию $condition.

Принимает следующие параметры:
$data - массив данных в формате имя_поля => значение.
$condition - Любое допустимое условие для выборки

validate($fields = null)

Проверяет модель на наличие ошибок. Если в качестве параметра передан массив, то проверяет только те поля, которые перечислены в массиве. Проверка осуществляется при помощи установленных для данного объекта валидаторов. Также поля проверяются на соответствие типу данных.

Этот метод полезно переопределять для создания проверок спецефичных для конкретной модели

Получение объектов

Получение объектов осуществляется описанными выше методами getById(), fetchOne() и find()

Условия для выборки

Условия для выборки передаются через параметр $conditions методов fetchOne() и find().

Рассмотрим синтаксис этого параметра:

Он может быть:

Cтрока, соотвествующая SQL - синтаксису WHERE

Например:

$productArr = Product::find('id > 2 AND id_rasdel = 2');

В этом случае синтаксис зависит от типа БД и применять его стоит только в крайнем случае, т.к. может ограничить переносимость скрипта между разными типами БД. К тому же это не безопасно. Тут надо проверять передаваемые условия, чтобы исключить возможность sql инъекций, экранировать строковые значения.

Массив

Элемент массива строка

1. строка соотвествует формату <колонка> <оператор (<, >, =, больше или равно, меньше или равно, не равно)> <значение>

Например:

$products = Product::find(array('id >= 2', 'id < 5'));

Строковые значения в этом случае экранируются автоматически.

Будьте внимательны! Выборка

$this->item = Unittest_Model_Item::find(array('uti_id=1 OR uti_id=3'));

будет интерпретирована как

SELECT `unittest_item`.* FROM `unittest_item` WHERE (uti_id = '1 OR uti_id=3')

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

2. Строка не соответствует указанному формату

Например:

$products = Product::find(array('id IN(1,2,5)'));

В этом случае условие принимается 'как есть' и добавляется к предложению WHERE, по аналогии с Cтрока, соотвествующая SQL - синтаксису WHERE Элементы массива добавляются к предложению WHERE с добавлением AND между ними.

Нарпимер:

$products = Product::find(array('id >= 2', 'id < 5'));

Соотвествует условию:

WHERE katalogshop_sale.id >= 2 AND katalogshop_sale.id < 5

Элемент массива - массив

Массив может состоять из 4-х элементов, из которых первые два являются обязательными.

Нарпимер:

$products = Product::find(array(
    array('id', '2'),
    array('id', '5', '<','OR')
));

Расмотрим элементы массива:

1-ый - поле в БД
2-ой - значение
3-ий - операнд (< > = больше или равно, меньше или равно, не равно и т.п.), если не указано, то принимается равным '='
4-ый - Условие объединения (AND ИЛИ OR), если не указано, то принимается равным 'AND'

Так приведенный пример соотвествует условию:

WHERE katalogshop_sale.id = 2 OR katalogshop_sale.id < 5

Если перый элемент массива равен 'RAW' или 'SQL' то к предложению WHERE добавляется второй элемент (значение) «Как есть», по аналогии с Cтрока, соотвествующая SQL - синтаксису WHERE

Значение может быть массивом

Например:

$cats = array(1, 2, 4);
$prod = Product::find(array(
    array('id_rasdel', $cats)
));

Будет соответствовать:

WHERE katalogshop_sale.id_rasdel IN (1,2,4);

$cats = array(1, 2, 4);
$prod = Product::find(array(
    array('id_rasdel', $cats, '<>')
));

Будет соответствовать условию:

WHERE katalogshop_sale.id_rasdel NOT IN (1,2,4);

Строковые значения в переданном массиве экранируются.

Значение может быть NULL

Например:

$prod = Product::find(array(
    array('id_rasdel', null)
));

Будет соответствовать:

WHERE katalogshop_sale.id_rasdel IS NULL;

$prod = Product::find(array(
    array('id_rasdel', null, '<>')
));

Будет соответствовать условию:

WHERE katalogshop_sale.id_rasdel IS NOT NULL;

Построение LIKE условий

Если значение содержит '*', то в предложение WHERE будет добавлено LIKE

Например:

$prod = Product::find(array(
    array('name', '*водонагреватель*')
));

Будет соответствовать условию:

WHERE katalogshop_sale.name LIKE '%водонагреватель%';

Так, к примеру для MySql '*' заменяется на '%'

Строковые значения экранируются.

Валидаторы. Проверка объектов.

Как уже отмечалось ранее, при сохранении объекта, его данные проходят проверку на соответствие типу данных, указанному в описании поля.

Дополнительную проверку данных можно обеспечить при помощи валидаторов.

Поддерживается 2 типа валидаторов:

Строковые валидаторы

В качестве строки выступает название типа данных: int, integer, bool, boolean, double, float, isnull, notnull, empty, notempty. Последние 4 - не являются типами данных и осуществляют проверку на соотвествие значения 'NULL' и на пустое значение.

Callback функции

В качестве валидатора можно передать функцию. Она должна по результатом проверки возвращать 'true' или строку с описанием ошибки.

Передача имени функции

Пример:

function myFunction($value){
// some validation
return true;
}
$prod = Product::getById(2);
$prod->setValidator('description', 'myFunction');

Использование анонимных функций

Пример:

$prod->setValidator('description', function($value){
    if(mb_strlen($value) > 30)  return true;
    return "Описание слишком короткое";
});

Использование методов классов

Пример:

class MyClass{
    public static function test($value)    {
        // some validation
        return true;
    }
}
$prod->setValidator('description', array('MyClass', 'test'));

Для нестатичного метода класса определение валидатора схоже с примером выше, с той разницей, что перед установкой валидатора нужно создать экземпляр класса и потом уже создать массив:

class MyClass {
    public function myMethod($value){
        // some validation
        return true;
    }
}
$object = new MyClass;
$prod->setValidator('description', array($object, 'myMethod'));

И, наконец, Вы можете определить в своем классе магический метод _invoke(). В этом случае в качестве валидатора просто передайте экземпляр класса.

class MyClass{
    public function __invoke($value) {
        // some validation
        return true;
    }
}

$object = new MyClass();
$prod->setValidator('description', $object);

Установка валидаторов

Валидаторы можно установить на стадии проектирования модели или в период выполнения в контроллере.

Для установки валидатора в классе модели следует переопределить метод validators(). Например:

protected function validators() {
    return array(
        array('specialization,birthdate,city,category,staff,skills,education', 'required'),
        array('staff', function ($value) {
            // Сделать невозможным указание одновременно уровней в штатном расписании «Стажер» c любым другим уровнем
            if(!empty($value) && in_array(5, $value) && count($value) > 1) {
                return 'Нельзя указать «Стажер» одновременно с другими уровнями в штатном расписании';
            }
            $ret = (count($value) < 3) ? true : 'Можно использовать не более двух уровней в штатном расписании';

            return $ret;
        }),
    );
}

Во время выполнения установить валидатор для поля объекта можно методом setValidator($field, $validators) Он принимает в качестве параметров имя поля и валидатор любого из перечисленных типов.

Например:

$prod = Product::getById(2);
$prod->setValidator('description', 'notempty');
$prod->setValidator('description', function($value){
    if(mb_strlen($value) > 30)  return true;
    return "Описание слишком короткое";
});

Получение списка валидаторов

получить валидаторы можно методом getValidators($field = null) Он возвращает массив валидаторов, установленных для заданного поля или все валидаторы объекта, если параметр опущен.

Сеттеры и Геттеры

Как и указывалось выше, доступ к полям записи в БД, представленной объектом производится через его свойства. Однако Вы можете переопределить стандартное поведение для некоторых полей или даже добавить объекту новые свойства, не привязанные к полям в БД.

Делается это при помощи волшебных методов - сеттеров и геттеров.

Например вы в классе модели можете добавить новое динамическое поле:

setMyField($val){
    $this->_myField = $val;
}

getMyField(){
    return $val;
}

Как видим формат имени метода: set<имя_поля_с_большой_буквы>. Префикс «set» используется для сеттера, а «get» - для геттера.

После этого мы можем обращаться к этим полям:

$object = module_model_Object::getById(2);

$object->myField = 15;
echo $object->myField;

Данный пример очень простой. Вы можете создать более сложную логику для своих сеттеров и геттеров. Переопределение сеттеров и геттеров для существующих полей происходит аналогично. Просто создайте метод с названием set<имя_существующего_поля_с_большой_буквы>.

Обратите внимание на то, что сеттер должен принимать значение.

Loader. Загрузчик

Tue, 06 May 2014 22:11:00 +0300

Этот компонент устарел и используется только для обратной совместимости. Используйте вместо него встроенный в Cotonti автозагрузчик Composer'a.

Класс «Loader», объявленный в файле «Loader.php» предназначен для автоматической загрузки описаний классов и интерфейсов. Автозагрузка происходит в момент первого обращения к классу и Вам не нужно беспокоиться о том, подключили Вы php-файл, содержащий описание класса или нет.

Для регистрации автозагрузчика в стэке __autoload служит статический метод register(). Вызывается так:

// Автозагрузка
require_once './lib/Loader.php';
Loader::register();

Регистрация автозагрузчика происходит в плагине cotonti-lib, так что Вам не нужно заботиться о подключении автозагрузчика в своих расширениях.

Метод регистрирует автозагрузчик только один раз. По этому даже если Вы его подключаете явно, ничего плохого не случится.

Как происходит автозагрузка:

Строка, задающая класс, согласно стандарта кодирования psr-0 (https://gist.github.com/Thinkscape/1234504), преобразуется в относительный путь посредством замены знаков подчеркивания разделителями директорий, используемыми в вашей ОС, и добавления расширения «.php». Например, для класса «files_model_File» на Windows будет использоваться путь «files\model\File.php».

Затем полученный файл ищется в папках «modules», «plugins», «lib» и папках заданных в настройке конфигурации include_path. Будет загружен первый встретившийся файл.

Так, если у Вас установлен модуль Файлов - «Files», то при первом обращении к упомянотому выше классу «files_model_File» будет загружен файл «modules/files/model/File.php»