Автор Тема: Документация  (Прочитано 147 раз)

SysBox

  • Администратор
  • Новичок
  • *****
  • Сообщений: 5
  • Администратор
    • Просмотр профиля
    • SysBox
Документация
« : 03 Ноябрь 2017, 15:46:55 »
SysBox - это простой фреймворк на PHP http://sysbox.ru
Название состоит из двух слов: System (система) и Box (коробка).

------------------
Основные принципы

1. Существуют коробки с системами.
Например коробка с админкой, коробка с библиотеками, коробка с сайтом1, коробка с сайтом2 и т.д.
Весь ваш код можно сложить в одну коробку или наоборот разбить на десятки коробок, как вам удобнее.
Каждая коробка это отдельный мир и может быть полностью автономна, даже со своим подключением к БД если нужно.
Или наоборот коробки могут активно запускать друг у друга методы, как вам удобнее.

2. Весь ваш код находится в методах классов.
Что бы запустить метод в текущей коробке достаточно к нему обратиться через $this. Пример так: $this->название класса->название метода();
При этом класс будет автоматически загружен и проинициализирован. На этом все построено.
Название класса обычно на 100% совпадает с путем до файла с этим классом.

3. Конфигурационный файл един для всех коробок.
Он компактный т.к. содержит общие правила и исключения из этих правил.
Автоматическая загрузка и инициализация классов происходит в соответствие с настройками.

------------------
Файлы двигателя

Box.php - Класс всех коробок
Config.php - Настройки
Action.php - Запуск метода по роут-строке
Engine.php - Двигатель
Error.php - Обработка ошибок
Exception.php - Для создания исключений PHP
Extend.php - Базовый класс для всех классов пользователя
Response.php - Формирует ответ сверверу
View.php - Работа с шаблонами
         
------------------
Файлы, классы

Весь пользовательски код SysBox находится внутри методов классов.
Класс всегда находится в отдельном файле. Один файл - один класс.
Одна коробка имеет свою персональную папку, в которой лежат файлы классов.
Файлы могут находится в корне или в подпапках на любой глубине.

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

(в примерах ниже /www/myBox/ - папка коробки)

/www/myBox/Test.php = Test
/www/myBox/Admin/Test.php = Admin_Test
/www/myBox/Admin/Test/Test.php = Admin_Test_Test

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

/www/myBox/MyTest.php = MyTest
/www/myBox/SuperAdmin/MyTest.php = SuperAdmin_MyTest

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

------------------
Запуск

1. Подключаем файл двигателя sysbox. Нужно только 1 раз за все время работы программы.
require('/www/sysbox/Engine.php');

2. Получаем от двигателя экземпляр коробки "admin". Экземпляров одной и той же коробки невозможно сделать много, он всегда один.
$Admin = \sysbox\engine\engine::getBox('admin');

3. Запускаем любые методы:
$Admin->Test1->myMethod1();
$Admin->Test2->myMethod2();
и т.д.

Для запуска напрямую из браузера:

1. Делаем так, что любые запросы к серверу приводят к запуску например index.php. При этом ему в переменной, например "_r", передается URL запроса к серверу. На сервере Apache для этого в файле .htaccess можно прописать подобное: RewriteRule ^([^?]*) /admin/index.php?_r=$1 [L,QSA]

2. Внутри index.php так же загружаем двигатель и инициализируем нужную коробку:
require('/www/sysbox/Engine.php');
$Admin = \sysbox\engine\engine::getBox('admin');

3.
// Выдаем браузеру результат работы метода в том виде, в котором запрашивали: html или json
$Admin->Response->setOutput(
   // Запуск класс->метод(аргументы) на основе роут-строки и GET данных
   // В данном случае роут-строка это URL запроса из браузера
   $Admin->Action->execute(
      array(
            'route' => $_REQUEST['_r'],
            'isBrowser' => true
        )
   )
);


В нем создается экземпляр класса-ядра SysBox и производится запуск действия $SysBox->action('') где передается строка - роут.
В этой строке указано в каком классе, какой метод, с какими параметрами запустить.
Такая строка формируется обычно на основе URL который запросили из браузера.
Например:

'subDir_fileClass__method__param1_param2'
где:
'subDir_fileClass' - название класса
'method' - метод в классе
'param1_param2' - параметры метода

Класс, метод и параметры разделяются двойным нижним подчеркиванием.
Если не указан метод, то будет запущен метод 'index'.
Если не указан класс, то будет запущен класс по умолчанию (задается в настройках коробки).
Если в строке контроллера последний символ /, то это означает, что передают URL и в нем файл не указан. По этому добавляется файл index (и в нем будет запущен метод index).
Параметры метода отделены друг от друга одним нижним подчеркиванием.
В строке контроллера можно не указывать первые большие буквы в названии класса (SysBox сам это поправит).
В названии класса можно использовать как нижние подчеркивания, так и любые слэши. Это позволяет браузеру "думать", что он запрашивает реальный файл лежащий в папке, а значит во вьюшах допустимо использовать относительные пути к jpg, css, js.
Например:
/subdir1/subdir2/fileClass__method__param1_param2 - $SysBox->Subdir1_Subdir2_FileClass->method(param1, param2);
/fileClass__method - $SysBox->FileClass->method();
/fileClass - $SysBox->FileClass->index();


Настройки
-----------

Все настройки находятся в одном файле /sysbox/config.php
Из себя представляют многомерный массив.
Первый уровень массива содержит глобальные настройки для всей системы в целом.
В элементе 'box' содержатся настройки конкретных коробок.
Зарезервировано название коробки 'default' - это не существующая, виртуальная коробка настройки которой имеют все остальные коробки по умолчанию.
В массиве каждой коробки имеется:



Автозагрузчик
-----------

В SysBox получить экземпляр класса можно 4 способами:

1. $this->initClass('Class', array(param1 => value1, param2 => value2));
Всегда будет создан новый экземпляр класса с указанными параметрами.

2. $this->getClass('Class', array(param1 => value1, param2 => value2));
При первом запросе будет создан и выдан экземпляр, при всех последующих будет выдаватьсь один и тот же экземпляр, причем параметры будут проигнорированы, если их указать. Параметры используются только при первой инициализации.

3. $this->Class(param1, param2);
То же самое, что $this->getClass.

4. $this->Class->myMethod();
То же самое, что $this->getClass, только без возможности явно указать параметры.

Под названием класса следует понимать не только реальное название класса, но и его алиас (сокращенное название). Используя любой из них можно получить экземпляр реального класса. Т.е. системе все равно, инициализировать реальный класс или алиас. Алиас может скрывать за собой даже класс из другой коробки.

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

В настройках каждой коробки есть асоциативный массив "initClass".
Ключ - название класса/алиаса.
Значение - подмассив с настройками класса/алиаса (все не обязательны).

В подмассиве:
box - название коробки откуда взять класс/алиас (если берем не из текущей коробки).
class - название класса/алиаса которое использовать для инициализации.
arguments - аргументы класса по умолчанию.



Алиасы
-----------

При инициализации классов/алиасов вместо $this можно использовать
$this->Box - экземпляр класса текущей коробки.
$this->getBox('otherBox') - любая другая коробка.

Обратиться к классу из другой коробки можно двумя способами:

1. прямое указание нужной коробки:
$this->getBox('otherBox')->Class->Method();

2. в настройках текущего класса создаем алиас указывающий на класс в другой коробке, далее просто инициализируем его как обычный класс:
$this->Class->Method();
Тут "Class" = алиас ведущий в другую коробку.

Коробки - это полноценный "синглтон". Экземпляр коробки всегда создается только один. Создаются экземпляры коробок не заранее, а по первому запросу.




Особенности:
-------------
1. Технических ограничений между контроллером, моделькой и шаблоном нет. Т.е. из любого места есть доступ к чему угодно. Можно писать в жестком MVC стиле, можно в произвольном.
2. Название класса совпадает и с URL и с папками, что позволяет MVC, JS, CSS, JPG и т.д. разместить в одной физической папке. Можно располагать файлы в жестком MVC стиле, а можно групировать в папки по произвольным признакам.
3. Namespace один и тот же у всех классов одной коробки. В названии класса указаны все подпапки и файл класса. Есть алиасы (сокращения названий) для классов текущей и других коробок.
4. Инициализация классов происходит путем обращения к нему $this->Class(); или $this->Class->randomMethod();
« Последнее редактирование: 05 Ноябрь 2017, 01:25:39 от SysBox »