Навчальний посібник
Zephir, і цей посібник, призначені для PHP-розробників, які хочуть створити C-розширення, але не знають C.
Ми припускаємо, що ви маєте досвід в одній або декількох інших мовах програмування. Ми проведемо паралелі з функціями PHP, C, JavaScript та іншими мовами. Ми акцентуватимемо увагу на функції Zephir, які є подібними до функцій в інших мовах, а також на функціях які є новими. Якщо ви знайомі з цими мовами вам буде простіше розібратися що до чого.
У цьому посібнику ми будемо використовувати стандартний термінал команд Linux. Якщо ви користувач Windows, потрібно замінити ці команди на аналогічні.
Перевірка встановлення
Якщо ви успішно встановили Zephir, тоді виконайте таку команду в консолі:
zephir help
Якщо все гаразд, ви повинні побачити такий список команд та логотип (або щось схоже):
_____ __ _
/__ / ___ ____ / /_ (_)____
/ / / _ \/ __ \/ __ \/ / ___/
/ /__/ __/ /_/ / / / / / /
/____/\___/ .___/_/ /_/_/_/
/_/
Zephir 0.12.2 by Andres Gutierrez and Serghei Iakovlev (4ab69bd9)
Usage:
command [options] [arguments]
Options:
--dumpversion Print the version of the compiler and don't do anything else
-h, --help Print this help message
--no-ansi Disable ANSI output
-V, --version Print compiler version information and quit
Available commands:
api Generates a HTML API based on the classes exposed in the extension
build Generates/Compiles/Installs a Zephir extension
clean Cleans any object files created by the extension
compile Compile a Zephir extension
fullclean Cleans any object files created by the extension (including files generated by phpize)
generate Generates C code from the Zephir code without compiling it
help Displays help for a command
init Initializes a Zephir extension
install Installs the extension in the extension directory (may require root password)
stubs Generates stubs that can be used in a PHP IDE
Якщо щось пішло не так, будь ласка, поверніться на сторінку Встановлення.
Каркас розширення
Перше, що нам потрібно зробити це згенерувати каркас розширення. Це створить базову структуру нашого розширення з якою ми працюватимемо далі. У нашому випадку ми створимо розширення під назвою utils (утиліти):
zephir init utils
Після цього в поточному робочому каталозі створиться каталог, що називається «utils»:
utils/
ext/
utils/
Каталог ext/ (всередині utils) містить код, який буде використовуватися компілятором для створення розширення. У каталозі є ще один каталог, який має таке ж ім’я, як і наше розширення, а саме utils. Ми розмістимо код Zephir в цьому каталозі.
Нам необхідно змінити робочий каталог на «utils», щоб почати компіляцію нашого коду:
cd utils
ls
ext/ utils/ config.json
Перегляд списку файлів покаже нам файл config.json. Цей файл містить параметри конфігурації, які ми можемо використовувати, щоб змінювати поведінку Zephir та/або розширення.
Додавання нашого першого класу
Zephir спроектований створювати об’єктно-орієнтовані розширення. Щоб почати розробку, нам потрібно додати наш перший клас до розширення.
Як і в багатьох інших мовах чи інструментах, перше, що ми хочемо побачити Привіт світ згенерований Zephir та перевірити чи все гаразд. Отже, наш перший клас називатиметься Utils\Greeting і міститиме метод, який друкуватиме Привіт світ!.
Код цього класу повинен бути поміщеним у utils/utils/greeting.zep:
namespace Utils;
class Greeting
{
public static function say()
{
echo "Привіт світ!";
}
}
Тепер ми маємо сказати Zephir, що наш проект треба зібрати та згенерувати розширення:
zephir build
Спочатку, і лише першого разу, виконається ряд внутрішніх команд, які створять необхідний код та конфігурації для експортування цього класу в PHP-розширення. Якщо все пройде без проблем в кінці ви побачите таке повідомлення:
...
Extension installed!
Add extension=utils.so to your php.ini
Don't forget to restart your web server
На цьому етапі, швидше за все, для встановлення розширення вам потрібно буде ввести ваш root пароль.
Зрештою, вам залишиться лише під’єднати ваше розширення у php.ini та перезапустити PHP-сервер. Щоб під’єднати ваше розширення, потрібно додати директиву extension=utils.so до файлу php.ini.
Примітка: Ви також можете під’єднати розширення через консоль за допомогою команди -d extension=utils.so, але це під’єднає його лише для одного запиту і вам доведеться писати цю команду для кожного запиту. Додавання ж директиви до php.ini забезпечить підключення вашого розширення для кожного запиту.
Первинне тестування
Тепер, коли розширення було додано до вашого php.ini, перевірте правильність завантаження розширення, виконавши наступну команду:
php -m
[PHP Modules]
Core
date
libxml
pcre
Reflection
session
SPL
standard
tokenizer
utils
xdebug
xml
Розширення utils повинно бути частиною виходу, що означає, що розширення завантажено правильно. Що ж, подивімося на наш Привіт світ, безпосередньо з-під PHP. Для цього ви можете створити простий PHP-файл, який викликає створений нами статичний метод:
<?php
echo Utils\Greeting::say(), "\n";
Вітаємо! У вас є перше розширення, яке працює з-під PHP.
Корисний клас
Метод Utils\Greeting::say хороший для перевірки, чи правильно налаштоване наше середовище. Тепер створімо кілька корисних класів.
Першим корисним класом, який ми додамо до розширення буде зручна фільтрація даних, які вводять користувачі. Цей клас називається Utils\Filter і його код повинен розміщуватися в файлі utils/utils/filter.zep:
Базовий каркас для цього класу:
namespace Utils;
class Filter
{
}
Клас містить фільтрації методи, які допоможуть фільтрувати небажані символи у рядках. Перший метод має назву alpha і його завдання полягає в тому, щоб відкинути усі символи, крім базових літер ASCII. Щоб почати, просто пройдемося по рядку та надрукуємо кожен байт через стандартний вивід:
namespace Utils;
class Filter
{
public function alpha(string str)
{
char ch;
for ch in str {
echo ch, "\n";
}
}
}
При виклику цього методу:
<?php
$f = new Utils\Filter();
$f->alpha("привіт");
Ви побачите:
п
р
и
в
і
т
Перевірити кожен символ у рядку є доволі просто. Тепер ми створимо інший рядок з правильними відфільтрованими символами:
class Filter
{
public function alpha(string str) -> string
{
char ch; string filtered = "";
for ch in str {
if (ch >= 'а' && ch <= 'я') || (ch >= 'А' && ch <= 'Я') {
let filtered .= ch;
}
}
return filtered;
}
}
Оновлений метод можна перевірити наступним чином:
<?php
$f = new Utils\Filter();
echo $f->alpha("!пр#02и3'121віт."); // надрукує "привіт"
У цьому скрінкасті ви можете подивитися, як створити розширення, описане в цьому посібнику:
Висновок
Це дуже простий посібник, і як ви бачите - почати створювати розширення із Zephir легко. Ми запрошуємо вас продовжувати читати документацію, щоб ви могли відкрити додаткові функції Zephir!