Навчальний посібник

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

If something went wrong, please return back to the installation page.

Каркас розширення

Перше, що нам потрібно зробити це згенерувати каркас розширення. Це створить базову структуру нашого розширення з якою ми працюватимемо далі. У нашому випадку ми створимо розширення під назвою 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віт."); // надрукує "привіт"

У цьому скрінкасті ви можете подивитися, як створити розширення, описане в цьому посібнику: <iframe src="//player.vimeo.com/video/84180223" width="500" height="313" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen mark="crwd-mark"></iframe>

Висновок

Це дуже простий посібник, і як ви бачите - почати створювати розширення із Zephir легко. Ми запрошуємо вас продовжувати читати документацію, щоб ви могли відкрити додаткові функції Zephir!