 |
- Содержание
- Добавление функций в PHP
Вызов пользовательских функций
Сообщения об ошибках
Все функции выглядят так:
void php3_foo(INTERNAL_FUNCTION_PARAMETERS) {
} |
Даже если ваша функция не принимает аргументов, вызывается она именно так.
Аргументы всегда имеют тип pval. Этот тип содержит объединение/union,
которое содержит фактический тип аргумента. Так, если ваша функция принимает
два аргумента, вы должны записать нечто такое в верхней части вашей функции:
Пример E-1. Аргументы функции
pval *arg1, *arg2;
if (ARG_COUNT(ht) != 2 || getParameters(ht,2,&arg1,&arg2)==FAILURE) {
WRONG_PARAM_COUNT;
} |
|
Примечание: аргументы могут передаваться по значению или по ссылке. В
обоих случаях вы должны передать &(pval *) в getParameters. Если
вы хотите проверить, передан n-ный параметр по ссылке или нет, вы можете
использовать функцию ParameterPassedByReference(ht,n). Она возвратит 1 или 0.
Если вы изменяете любой из переданных параметров, переданы ли они по ссылке
или нет, вы можете начать работу с данным параметром, вызвав pval_destructor на
нём, или, если это ARRAY, в который вы хотите добавить данные, вы можете
использовать функции, аналогичные тем, которые находятся в
internal_functions.h и манипулируют return_value как ARRAY.
Также, если вы изменяете параметр на IS_STRING, не забудьте сначала
присвоить новую estrdup()'ированную строку и размер строки и только после этого
изменяйте тип на IS_STRING. Если вы изменяете строку параметра, который уже
является IS_STRING или IS_ARRAY, вы должны сначала запустить на нём pval_destructor.
Функция может принимать переменное количество аргументов. Если ваша
функция может принять 2 или 3 аргумента, используйте следующее:
Пример E-2. Переменное
количество аргументов функции
pval *arg1, *arg2, *arg3;
int arg_count = ARG_COUNT(ht);
if (arg_count < 2 || arg_count > 3 ||
getParameters(ht,arg_count,&arg1,&arg2,&arg3)==FAILURE) {
WRONG_PARAM_COUNT;
} |
|
Тип каждого аргумента хранится в поле (свойстве) типа pval. Этот тип может
быть одним из следующих: Таблица E-1. Внутренние типы PHP
| IS_STRING | Строка |
| IS_DOUBLE | Число с плавающей точкой двойной точности |
| IS_LONG | Длинное целое число |
| IS_ARRAY | Массив | | IS_EMPTY |
None/Ничего | | IS_USER_FUNCTION |
?? | | IS_INTERNAL_FUNCTION |
?? (если что-то из этого не может быть передано функции - удаляется) |
| IS_CLASS | ?? | | IS_OBJECT |
?? |
Если вы получаете аргумент одного типа и хотите использовать его как другой
тип, или если вы просто хотите форсировать приведение аргумента к определённому
типу, вы можете использовать одну из следующих функций конвертации типа:
convert_to_long(arg1);
convert_to_double(arg1);
convert_to_string(arg1);
convert_to_boolean_long(arg1); /* Если строка равна "" или "0", она становится 0,
в ином случае 1 */
convert_string_to_number(arg1); /* Конвертирует строку в LONG или в
DOUBLE, в зависимости от строки */ |
Все эти функции выполняют конвертацию на месте/in-place. Они ничего не возвращают.
Реальный аргумент хранится в union; членами являются: IS_STRING: arg1->value.str.val IS_LONG: arg1->value.lval IS_DOUBLE: arg1->value.dval
Любая необходимая функции память должна быть выделена с помощью emalloc() или estrdup(). Это абстрактные функции работы с памятью, которые
выглядят и работают как нормальные функции malloc() и
strdup(). Память должна освобождаться с помощью efree().
В программе имеются два вида памяти: память, которая возвращается
разборщику в переменной, и память, которая нужна вам для временного хранения в
вашей внутренней функции. Если вы присваиваете строку переменной, возвращаемой
разборщику, вы должны сначала выделить память с помощью emalloc() или
estrdup(). Эта память НИКОГДА НЕ ДОЛЖНА освобождаться вами, если только вы
позднее не переписываете в этой же функции первоначальное присвоение
(хотя этот стиль программирования нельзя приветствовать).
Для любого временного/постоянного выделения памяти, необходимой вам в
функции/библиотеке, вы должны использовать три функции: emalloc(), estrdup() и efree().
Они ведут себя ТОЧНО ТАК ЖЕ, как и их функции-двойники. Всё что вы emalloc() или estrdup(), вы должны efree()
в той или иной точке, если это не предполагается делать в конце программы;
иначе это приведёт к утечке памяти. Фраза "Они ведут себя ТОЧНО ТАК ЖЕ, как и их
функции-двойники" означает: если вы efree() то, что не было
emalloc()'овано или estrdup()'овано, вы можете получить нарушение
сегментации. Поэтому, пожалуйста, будьте бдительны и освобождайте всю выделенную память.
Если вы компилируете с опцией "-DDEBUG", PHP будет выводить весь листинг
памяти, выделенной с помощью emalloc() и estrdup(), но не освобождённой с
помощью efree(), при запуске специфицированного скрипта.
Имеются несколько макросов, которые облегчают установку переменной в таблице символов:
SET_VAR_STRING(name,value) SET_VAR_DOUBLE(name,value) SET_VAR_LONG(name,value)
| Предупреждение | |
Соблюдайте осторожность при использовании SET_VAR_STRING. Для части value
обязана быть выделена память, поскольку код обслуживания памяти будет
пытаться освободить эту позицию позднее. Не передавайте статически размещённую память в SET_VAR_STRING. |
Таблицы символов в PHP реализованы как хэш-таблицы. В любое данное время &symbol_table
является указателем на 'главную/main' таблицу символов, а active_symbol_table
указывает на текущую активную таблицу символов (они могут быть идентичны, как
при старте, или разными, если вы находитесь внутри функции).
В следующих примерах использована 'active_symbol_table'. Вы должны
заменить её на &symbol_table, если хотите работать именно с 'main' таблицей
символов. Также эта же функция может применяться к массивам, как разъясняется ниже.
Пример E-3. Проверка существования $foo а таблице символов
if (hash_exists(active_symbol_table,"foo",sizeof("foo"))) { exists... }
else { doesn't exist } |
|
Пример E-4. Определение размера переменной в таблице символов
hash_find(active_symbol_table,"foo",sizeof("foo"),&pvalue);
check(pvalue.type); |
|
Массивы в PHP реализованы с использованием тех же хэш-таблиц, что и в
таблицах символов. Это значит, что две вышеприведённые функции могут
также использоваться для проверки переменных в массивах. Если вы хотите определить новый
массив в таблице символов, вы должны сделать следующее:
Сначала может понадобиться проверка существования массива и
соответствующего выхода через использование hash_exists() или hash_find().
Инициализируем массив:
Пример E-5. Инициализация нового массива
pval arr;
if (array_init(&arr) == FAILURE) { failed... };
hash_update(active_symbol_table,"foo",sizeof("foo"),&arr,sizeof(pval),NULL); |
|
Этот код объявляет новый массив $foo в активной таблице символов. Это пустой массив.
Вот как добавить в него новые вхождения:
Пример E-6. Добавление вхождений в новый массив
pval entry;
entry.type = IS_LONG;
entry.value.lval = 5;
/* определяется $foo["bar"] = 5 */
hash_update(arr.value.ht,"bar",sizeof("bar"),&entry,sizeof(pval),NULL);
/* определяется $foo[7] = 5 */
hash_index_update(arr.value.ht,7,&entry,sizeof(pval),NULL);
/* определяется следующее свободное место в $foo[],
* $foo[8], как 5 (работает аналогично php2)
*/
hash_next_index_insert(arr.value.ht,&entry,sizeof(pval),NULL); |
|
Если вы хотите изменить значение, вставленное в хэш, вы обязаны сначала
запросить его из хэша. Чтобы избежать этой лишней работы, вы можете
предоставить pval ** функции add хэша, и он будет обновлён pval *-адресом
элемента, вставленного в хэш. Если это значение равно NULL (как во всех предыдущих примерах) -
этот параметр игнорируется. hash_next_index_insert() использует примерно ту же логику, что
и "$foo[] = bar;" в PHP 2.0. Если вы конструируете массив для возвращения из функции, вы можете
инициализировать этот массив, выполнив следующее:
if (array_init(return_value) == FAILURE) { failed...; } |
... а затем добавляя значения вспомогательными функциями:
add_next_index_long(return_value,long_value);
add_next_index_double(return_value,double_value);
add_next_index_string(return_value,estrdup(string_value)); |
Конечно, если добавление не выполняется сразу после инициализации массива,
вам сначала нужно будет найти этот массив:
pval *arr;
if (hash_find(active_symbol_table,"foo",sizeof("foo"),(void **)&arr)==FAILURE)
{ can't find... }
else { use arr->value.ht... } |
Заметьте, что hash_find получает указатель на указатель pval, а не указатель pval.
Любая функция хэша возвращает SUCCESS или FAILURE (кроме hash_exists(), которая возвращает булево значение).
Имеются несколько макросов для облегчения получения return-значений из функций.
Все макросы RETURN_* устанавливают return-значение и возвращают его из функции: -
RETURN RETURN_FALSE RETURN_TRUE RETURN_LONG(l) RETURN_STRING(s,dup) Если dup равно TRUE, дублирует строку RETURN_STRINGL(s,l,dup) Возвращает строку (s), специфицируя длину (l) RETURN_DOUBLE(d)
Макросы RETVAL_* устанавливают, но не возвращают, return-значение.
RETVAL_FALSE RETVAL_TRUE RETVAL_LONG(l) RETVAL_STRING(s,dup) Если dup равно TRUE, дублирует строку RETVAL_STRINGL(s,l,dup) Возвращает строку (s), специфицируя длину (l) RETVAL_DOUBLE(d) Все вышеприведённые строковые макросы будут estrdup() передаваемый аргумент 's',
поэтому вы можете безопасно освободить аргумент после вызова макроса или,
альтернативно, использовать статически размещённую память.
Если ваша функция возвращает булевы ответы success/error, всегда
используйте RETURN_TRUE и RETURN_FALSE, соответственно.
Ваша функция может также возвращать сложные типы данных, такие как объект/object или массив/array.
Возвращение объекта: Вызвать object_init(return_value). -
Заполнить его значениями. Функции, предназначенные для этого, перечислены ниже. -
Возможно, зарегистрировать функции для этого объекта.
Чтобы получать значения из объекта, функции понадобится получить "this"
из active_symbol_table. Его тип должен быть IS_OBJECT, и это как правило таблица регулярного хэш
(т.е. вы можете использовать функции регулярного хэша на .value.ht).
Фактическая регистрация функции может быть выполнена с использованием :
add_method( return_value, function_name, function_ptr );
|
Функции для заполнения объекта: add_property_long( return_value,
property_name, l ) - Добавляет свойство с именем 'property_name', типом long, равное 'l' add_property_double( return_value,property_name, d ) - То же самое, только double add_property_string( return_value,property_name, str ) - То же самое, только string add_property_stringl( return_value,property_name, str, l ) - То же самое, только string длиной 'l'
Возвращение массива: Вызвать array_init(return_value) Заполнить его значениями. Функции для этого перечислены ниже.
Вот функции для заполнения массива: add_assoc_long(return_value,key,l) - добавляет ассоциативное вхождение/entry с
ключом 'key' и long-значением 'l' add_assoc_double(return_value,key,d) add_assoc_string(return_value,key,str,duplicate) add_assoc_stringl(return_value,key,str,length,duplicate) - специфицирует длину строки add_index_long(return_value,index,l) - добавляет вхождение в индексе 'index' с long-значением 'l' add_index_double(return_value,index,d) add_index_string(return_value,index,str) add_index_stringl(return_value,index,str,length)- специфицирует длину строки add_next_index_long(return_value,l) - добавляет вхождение в массиве в следующем свободном смещении с long-значением 'l' add_next_index_double(return_value,d) add_next_index_string(return_value,str) add_next_index_stringl(return_value,str,length) - специфицирует длину строки
PHP имеет стандартные способы работы с ресурсами различных типов. Это
замена всех локальных связанных списков PHP 2.0. Доступны функции: -
php3_list_insert(ptr, type) - возвращает 'id' вновь вставленного ресурса
php3_list_delete(id) - удаляет ресурс со специфицированным id php3_list_find(id,*type) - возвращает указатель ресурса со специфицированным id,
обновляет 'type' до типа ресурса
Обычно эти функции используются для SQL-драйверов, но могут также
использоваться для чего угодно; например, для обслуживания дескрипторов файлов. Типичный листинг
кода выглядит так:
Пример E-7. Добавление нового ресурса
RESOURCE *resource;
/* ...разместить память для ресурса и получить ресурс... */
/* добавить новый ресурс в список */
return_value->value.lval = php3_list_insert((void *) resource, LE_RESOURCE_TYPE);
return_value->type = IS_LONG; |
|
Пример E-8. Использование существующего ресурса
pval *resource_id;
RESOURCE *resource;
int type;
convert_to_long(resource_id);
resource = php3_list_find(resource_id->value.lval, &type);
if (type != LE_RESOURCE_TYPE) {
php3_error(E_WARNING,"resource index %d has the wrong type",resource_id->value.lval);
RETURN_FALSE;
}
/* ...использовать ресурс... */ |
|
Пример E-9. Удаление существующего ресурса
pval *resource_id;
RESOURCE *resource;
int type;
convert_to_long(resource_id);
php3_list_delete(resource_id->value.lval); |
|
Типы ресурсов должны быть зарегистрированы в php3_list.h, в enum
list_entry_type. Кроме того, нужно добавить shutdown-код для любого вновь
определённого типа ресурса в list.c's list_entry_destructor()
(даже если вы ничего особенного при отключении/shutdown делать не хотите, вы обязаны добавить пустой case).
В PHP есть стандартный способ хранения постоянных ресурсов (т.е.
ресурсов, хранимых между вызовами). Первым эту возможность использовал
модуль MySQL, а затем mSQL, поэтому можно получить представление о том,
как нужно использовать постоянные ресурсы, просмотрев mysql.c. Вам нужно просмотреть функции:
| php3_mysql_do_connect | | php3_mysql_connect() |
| php3_mysql_pconnect() |
Общая идея постоянных модулей такова:
Кодировать все ваши модули для работы со списком регулярных ресурсов, рассмотренным в разделе (9). Кодировать дополнительные connect-функции, которые проверяют, существует ли уже
ресурс в списке постоянных ресурсов. Если существует, зарегистрировать
его в списке постоянных ресурсов как указатель на список существующих
ресурсов (поскольку если 1., остальной код должен сработать немедленно).
Если не существует, создать его, добавить его в список существующих
ресурсов И добавить указатель на него из списка регулярных ресурсов,
чтобы весь код мог работать, пока он находится в списке регулярных
ресурсов, но при следующем подключении ресурс может быть найден уже в
списке существующих ресурсов и использован без необходимости его
повторного создания. Вы должны регистрировать эти ресурсы с различными
типами (например, LE_MYSQL_LINK для несуществующей ссылки и LE_MYSQL_PLINK
- для существующей ссылки).
Если вы просмотрите mysql.c, обратите внимание, что, за исключением более
сложной функции connect, остальная часть модуля не изменилась.
Точно такой же интерфейс имеется для списка регулярных ресурсов и для
списка постоянных ресурсов, только 'list' заменено на 'plist': -
php3_plist_insert(ptr, type) - возвращает 'id' вновь вставленного ресурса
php3_plist_delete(id) - удаляет ресурс со специфицированным id php3_plist_find(id,*type) - возвращает указатель ресурса со специфицированным id,
обновляет 'type' на тип этого ресурса
Более вероятно, однако, что эти функции окажутся бесполезны при попытке реализовать постоянный модуль.
Обычно бывает нужно использовать тот факт, что список постоянных ресурсов
является в действительности хэш-таблицей. Например, в модулях
MySQL/mSQL, когда есть вызов pconnect() (постоянное
connect), функция строит строку вывода host/user/passwd, которая передаётся
этой функции, и хэширует SQL-ссылку этой строкой как ключом/key. При следующем вызове pconnect()
с теми же host/user/passwd, будет сгенерирован тот же key, и функция найдёт SQL-ссылку в постоянном списке.
Пока документация отсутствует, вы должны просмотреть в mysql.c или в msql.c,
как можно использовать возможности хэш-таблиц plist'ов.
Одно важное замечание: ресурсы, входящие в список постоянных ресурсов
обязаны *НЕ* размещаться менеджером памяти PHP,
т.е. они НЕ должны создаваться с помощью emalloc(), estrdup(), etc.
Вместо этого нужно использовать регулярные malloc(), strdup(), etc.
Причина проста - в конце запроса (в конце запуска) каждый участок памяти,
выделенный менеджером памяти PHP, удаляется. Поскольку не предполагается
удаление постоянного списка в конце запроса, менеджер памяти PHP нельзя
использовать для размещения ресурсов, входящих в этот список.
Если вы регистрируете ресурс, вводимый в постоянный список, вы должны
добавить для него деструктор как в постоянный, так и в непостоянный списки.
Деструктор в деструкторе непостоянного списка ничего делать не должен.
Деструктор в деструкторе постоянного списка должен соответствующим образом
освобождать ресурсы, полученные данным типом (память, SQL-ссылки etc).
Как и с непостоянными ресурсами, вы *ОБЯЗАНЫ* добавить деструкторы каждому
ресурсу, даже если он не требует уничтожения и деструктор может быть
пустым. Запомните: поскольку emalloc() и компания не используются в
сочетании с постоянным списком, вы обязаны не использовать здесь efree() вообще.
Многие свойства PHP могут конфигурироваться на этапе прогона программы.
Эти директивы конфигурации могут появляться или в файле php3.ini, или - в случае с версией Apache-модуля -
Apache .conf-файлах. Преимущество их присутствия в Apache
.conf-файлах заключается в том, что они могут быть сконфигурированы на
уровне директорий. Это означает, что одна директория может иметь одну
safemodeexecdir, например, а другая директория - другую. Эта дробность
конфигурации особенно необходима, когда сервер поддерживает наличие несколько виртуальных хостов.
Вот шаги по добавлению новой директивы: -
Добавить директиву в структуру php3_ini_structure в mod_php3.h.
В main.c отредактировать функцию php3_module_startup
и добавить соответствующий вызов cfg_get_string() или cfg_get_long(). Добавить директиву, ограничения и комментарий в структуру php3_commands в mod_php3.c.
Обратите внимание на часть restrictions/ограничений. RSRC_CONF являются директивами, которые могут
находится только в текущих Apache .conf-файлах. Любые директивы OR_OPTIONS
могут находиться в любом месте, включая нормальные .htaccess-файлы. В php3take1handler() или в php3flaghandler() добавить соответствующее вхождение для вашей директивы.
В разделе конфигурации/configuration функции
_php3_info() в functions/info.c вам необходимо добавить вашу новую директиву. И наконец - вы, конечно, должны использовать новую вашу директиву где-нибудь.
Она будет адресоваться как php3_ini.directive.
|