Verification: a143cc29221c9be0

Php array to number one

What is a PHP Array?

A PHP array is a variable that stores more than one piece of related data in a single variable.

Think of an array as a box of chocolates with slots inside.

The box represents the array itself while the spaces containing chocolates represent the values stored in the arrays.

The diagram below illustrates the above syntax.
 

In this tutorial, you will learn-

  • Numeric Arrays
  • PHP Associative Array
  • PHP Multi-dimensional arrays
  • PHP Array operators

Numeric Arrays

Numeric arrays use number as access keys.

An access key is a reference to a memory slot in an array variable.

The access key is used whenever we want to read or assign a new value an array element.

Below is the syntax for creating numeric array in php. Array Example

Or

 value, …);
?>

HERE,

  • “$variable_name…” is the name of the variable
  • “[n]” is the access index number of the element
  • “value” is the value assigned to the array element.

Let’s now look at an example of a numeric array.

Suppose we have 5 movies that we want to store in array variables.

We can use the example shown below to do that.

Here,

Each movie is given an index number that is used to retrieve or modify its value. Observe the following code-

Output:

Once upon a time in China Eastern Condors

As you can see from the above examples, working with arrays in PHP when dealing with multiple values of the same nature is very easy and flexible.

Alternatively, the above array variables can also be created using the following code.

 "Shaolin Monk",
               1 => "Drunken Master",
               2 => "American Ninja",
               3 => "Once upon a time in China",
               4 =>"Replacement Killers" );
echo $movie[4];
?>

Output:

Replacement Killers

PHP Associative Array

Associative array differ from numeric array in the sense that associative arrays use descriptive names for id keys.

Below is the syntax for creating associative array in php.

 value);
?>

HERE,

  • “$variable_name…” is the name of the variable
  • “['key_name']” is the access index number of the element
  • “value” is the value assigned to the array element.

  Let’s suppose that we have a group of persons, and we want to assign the gender of each person against their names.

We can use an associative array to do that.The code below helps us to do that.

 "Female", "John" => "Male", "Mirriam" => "Female");
print_r($persons); 
echo ""; 
echo "Mary is a " . $persons["Mary"];
?>

 HERE,

Output:

Array ( [Mary] => Female [John] => Male [Mirriam] => Female ) Mary is a Female

Associative array are also very useful when retrieving data from the database.

The field names are used as id keys.

PHP Multi-dimensional arrays

These are arrays that contain other nested arrays.

The advantage of multidimensional arrays is that they allow us to group related data together.

Let’s now look at a practical example that implements a php multidimensional array.

The table below shows a list of movies by category.

Movie title Category
Pink Panther Comedy
John English Comedy
Die Hard Action
Expendables Action
The Lord of the rings Epic
Romeo and Juliet Romance
See no evil hear no evil Comedy

The above information can be represented as a multidimensional array. The code below shows the implementation.

 array("Pink Panther", "John English", "See no evil hear no evil"),
"action" => array("Die Hard", "Expendables"),
"epic" => array("The Lord of the rings"),
"Romance" => array("Romeo and Juliet")
);
print_r($movies);
?>

  HERE,

Output:

Array ( [comedy] => Array ( [0] => Pink Panther [1] => John English [2] => See no evil hear no evil ) [action] => Array ( [0] => Die Hard [1] => Expendables ) [epic] => Array ( [0] => The Lord of the rings ) [Romance] => Array ( [0] => Romeo and Juliet ) )

Another way to define the same array is as follows

 array(

                                0 => "Pink Panther",

                                1 => "john English",

                                2 => "See no evil hear no evil"

                                ),

                "action" => array (

                                0 => "Die Hard",

                                1 => "Expendables"

                                ),

                "epic" => array (

                                0 => "The Lord of the rings"

                                ),

                "Romance" => array

                                (

                                0 => "Romeo and Juliet"

                                )

);
echo $film["comedy"][0];
?>

Output:

Pink Panther

  Note: the movies numeric array has been nested inside the categories associative array

PHP Arrays: Operators

Operator Name Description How to do it Output
x + y Union Combines elements from both arrays
 1);

$y = array('value' => 10);

$z = $x + $y;
?>
Array([id] => 1 [value] => 10)
X == y Equal Compares two arrays if they are equal and returns true if yes.
 1);

$y = array("id" => "1");

if($x == $y)
{
echo "true";
}
else
{
echo "false";

}
?>
True or 1
X === y Identical Compares both the values and data types
 1);

$y = array("id" => "1");

if($x === $y)
{
echo "true";
}
else
{
echo "false";
}
?>
False or 0
X != y, x y Not equal  
 1);

$y = array("id" => "1");

if($x != $y)
{
echo "true";
}
else
{
echo "false";
}
?>
False or 0
X !== y Non identical  
 1);

$y = array("id" => "1");

if($x !== $y)
{
echo "true";
}
else
{
echo "false";
}
?>
True or 1

PHP Array Functions

Count function

The count function is used to count the number of elements that an php array contains. The code below shows the implementation.

Output:

3

is_array function

The is_array function is used to determine if a variable is an array or not. Let’s now look at an example that implements the is_array functions.

Output:

1

Sort

This function is used to sort arrays by the values.

If the values are alphanumeric, it sorts them in alphabetical order.

If the values are numeric, it sorts them in ascending order.

It removes the existing access keys and add new numeric keys.

The output of this function is a numeric array

 "Female", "John" => "Male", "Mirriam" => "Female");

sort($persons);

print_r($persons);
?>

Output:

Array ( [0] => Female [1] => Female [2] => Male )

ksort

This function is used to sort the array using the key. The following example illustrates its usage.

 "Female", "John" => "Male", "Mirriam" => "Female");

ksort($persons);

print_r($persons);
?>

Output:

Array ( [John] => Male [Mary] => Female [Mirriam] => Female )

asort

This function is used to sort the array using the values. The following example illustrates its usage.

 "Female", "John" => "Male", "Mirriam" => "Female");

asort($persons);

print_r($persons);

?>

Output:

Array ( [Mary] => Female [Mirriam] => Female [John] => Male )

Why use arrays?

  • Contents of Arrays can be stretched,
  • Arrays easily help group related information such as server login details together
  • Arrays help write cleaner code.

Взаимосвязь свойства length с числовыми свойствами массивов

Некоторые встроенные методы массива (например, join, slice, indexOf и т.д.) учитывают значение свойства length при своём вызове. Другие методы (например, push, splice и т.д.) в результате своей работы обновляют свойство length массива.

При установке свойства в массиве, если свойство имеет действительный индекс и этот индекс выходит за пределы текущих границ массива, движок соответствующим образом обновит свойство length:

const numArray = [12, 45, 67, 456, 34];

let value = numArray.length;

console.log(value, numArray); // 5 Array(5) [ 12, 45, 67, 456, 34 ]

numArray.length = 0;

console.log(numArray); // [] - получили пустой массив

numArray.length = 100;

console.log(numArray); // (100) [empty × 100] - получили массив из 100 элементов, так как перезаписали свойство массива length

Уменьшение свойства length приводит к удалению элементов массива:

var arr = ["Alex", "Mary", "Serg"];

console.log(arr.length); // 3

console.log(arr); // Array(3) [ "Alex", "Mary", "Serg" ]

arr.length= 1;

console.log(arr); // Array [ "Alex" ]

Для исключения появления разреженных массивов при удалении или добавлении элементов следует использовать специальные методы push(), unshift(), pop(), shift()

Добавление элемента в конец массива (метод push() )

Метод push():

  • присоединяет элементы к концу массива, используя для определения места вставки свойство length;
  • возвращает новое значение свойства length объекта, для которого был вызван данный метод. 

Метод push не является привязанным к типу Array: этот метод может быть вызван или применён и к массивоподобным объектам. 

Особенности метода push():

  1. Если свойство length не может быть преобразовано в число, будет использован индекс 0. Если свойство length не существует, то в этом случае оно будет создано.
  2. К строкам (как массивоподобным объектам) метод push() применён быть не может, так как строки являются неизменяемыми.

const numArray = [12, 45, 67, 456, 34];

let value;

value = numArray.push(100); // добавление элемента в конец массива, переменная value принимает новое значение свойства length

console.log(value, numArray); // 6 Array(6) [ 12, 45, 67, 456, 34, 100 ]

Примеры

Функция, которая принимает значение переменной n и возвращает массив, заполненный числами от 1 до n

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

function getArray(num) {

  const arr = [];

  for (let i = 0; i num; i++) {

    arr.push[i]; // в данном случае это аналог arr[i] = i + 1;    

  }

  return arr;

}

// ИЛИ

function returnArray(n) {

  let myArray = [];

  while (n > 0) {

    myArray.push(n);

    n--;

  }

  return myArray;

}

[свернуть]

Добавление элемента в начало массива (метод unshift() )

Метод unshift():

  • добавляет элементы в начало массива;
  • возвращает новое значение свойства length объекта, для которого был вызван данный метод. 

Метод unshift() не является привязанным к типу Array: этот метод может быть вызван или применён и к массивоподобным объектам. 

const numberArray = [12, 45, 67, 456, 34];

let value;

value = numberArray.unshift(200,100); // добавление элементов в начало массива, переменная value принимает новое значение свойства length

console.log(value, numberArray); // 7 Array (7) [200, 100, 12, 45, 67, 456, 34]

// Ещё пример

const numArray = [10];

numArray.unshift([-200]); // добавление элементов в начало массива

console.log(numArray); // Array (2) [[-200], 10]

Удаление элемента с конца массива (метод pop() )

Метод pop():

  • удаляет последний элемент из массива (изменяет длину массива);
  • возвращает значение удаленного из массива элемента (или undefined, если массив пуст).

Метод pop() не является привязанным к типу Array: этот метод может быть вызван или применён и к массивоподобным объектам. 

const numberArray = [200, 12, 45, 67, 456, 34, 100];

let value;

value = numberArray.pop(); // удаление элемента с конца массива 

console.log(value, numberArray); // 100 Array(6) [ 200, 12, 45, 67, 456, 34 ]

Удаление элемента из начала массива (метод shift() )

Метод shift():

  •  удаляет первый элемент из массива (изменяет длину массива, последовательно сдвигая значения индексов по направлению к нулю);
  • возвращает значение удаленного из массива элемента (или undefined, если массив пуст).

const numberArray = [200, 12, 45, 67, 456, 34, 100];

let value;

value = numberArray.shift(); // удаление элемента из начала массива, в value записывается значение удаленного элемента

console.log(value, numberArray); // 200 Array(6) [ 12, 45, 67, 456, 34, 100 ]

console.log(numberArray[0]); // 12 (индексы сдвинуты к началу)

HIVE

HIVE («Улей») - это массив памяти для хранения переменных вашего фреймворка в виде пар ключ⇒значение. Сохранение значения в hive обеспечивает его глобальную доступность для всех классов и методов вашего приложения.

set

Привязать значение к ключу Hive

mixed set ( string $key, mixed $val [, int $ttl = 0 ] )

Примеры установки переменных фреймворка:

$f3->set('a',123); // a=123, integer
$f3->set('b','c'); // b='c', string
$f3->set('c','whatever'); // c='whatever', string
$f3->set('d',TRUE); // d=TRUE, boolean

Определение массивов:

$f3->set('hash',array( 'x'=>1,'y'=>2,'z'=>3 ) );
// dot notation is also possible:
$f3->set('hash.x',1);
$f3->set('hash.y',2);
$f3->set('hash.z',3);

Определение свойств объекта:

$f3->set('a',new \stdClass);
$f3->set('a->hello','world');
echo $f3->get('a')->hello; // world

более короткий синтаксис ArrayAccess, начиная с F3 v3.4.0

$f3->LANGUAGE = 'en';
$f3->foo = 1234;
$f3['bar'] = 'buzzword';

Кэширование свойств

Если параметр $ttl > 0 и механизм кэширования F3 включен, указанная переменная будет кэшироваться в течение $ttl секунд. Уже кэшированные переменные будут обновлены путем повторного использования старого срока действия.

Если вам нужно кэшировать переменные на бесконечное время, проверьте метод Cache→set .

Вы можете кэшировать строки, массивы и все другие типы - даже объекты. get() автоматически загрузит их из кэша.

Примеры кэширования:

// cache string
$f3->set('simplevar','foo bar 1337', 3600); // cache for 1 hour
//cache big computed arrays
$f3->set('fruits',array(
    'apple',
    'banana',
    'peach',
), 3600);
// cache objects
$f3->set('myClass1', new myClass('arg1'), 3600);
// change expire time for a single cookie var
$f3->set('COOKIE.foo', 123, 3600);  // 1 hour
$f3->set('COOKIE.bar', 456, 86400); // 1 day

Системные переменные

Фреймворк имеет собственные системные переменные. Вы можете изменить их, чтобы изменить поведение фреймворка, например:

$f3->set('CACHE', TRUE);
$f3->set('HALT', FALSE);
$f3->set('CASELESS', FALSE);

Также можно установить глобальные переменные PHP с помощью системных переменных F3 COOKIE, GET, POST, REQUEST, SESSION, FILES, SERVER, ENV. Эти 8 переменных автоматически синхронизируются с базовыми глобальными переменными PHP.

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

Помните : ключи Hive чувствительны к регистру.

Кроме того, ключи HIVE проверяются на соответствие этим разрешенным символам: [a_zA_Z0-9]

get

Получить содержимое ключа hive

mixed get ( string $key [, string|array $args = NULL ] )

Чтобы получить значение ранее сохраненной переменной, используйте:

$f3->set('myVar','hello world');
echo $f3->get('myVar'); // outputs the string 'hello world'
$local_var = $f3->get('myVar'); // $local_var holds the string 'hello world'

Если возвращаемое значение представляет собой строку, содержащую один или несколько заполнителей формата, аргументы могут быть переданы непосредственно после имени ключа:

$f3->set('var1','Current date: {0,date} - Current time: {0,time}');
$f3->set('var2','Departure: {0,date} - Arrival: {1,date}');
echo $f3->get('var1',time());//shorthand for $f3->format($f3->get('var1'),time());
echo $f3->get('var2',array($timestamp1,$timestamp2));//shorthand for $f3->format($f3->get('var2'),$timestamp1,$timestamp2);

Примечание: когда кэширование включено и переменная не была определена во время выполнения раньше, F3 пытается загрузить переменную из кэша при использовании get ().

Доступ к массивам прост. Вы также можете использовать точечную нотацию JS 'myarray.bar', что значительно упрощает чтение и запись.

$f3->set('myarray',
           array(
                    0 => 'value_0',
                    1 => 'value_1',
                'bar' => 123,
                'foo' => 'we like candy',
                'baz' => 4.56,
                )
         );
 
echo $f3->get('myarray[0]'); // value_0
echo $f3->get('myarray.1'); // value_1
echo $f3->get('myarray.bar'); // 123
echo $f3->get('myarray["foo"]'); // we like candy
echo $f3->get('myarray[baz]'); // 4.56, notice alternate use of single, double and no quotes
// a new ArrayAccess syntax is also possible since v3.4.0
echo $f3->myarray['foo']; 
echo $f3['myarray']['baz'];

sync

Синхронизация глобальной переменной PHP с соответствующим ключом hive

array sync ( string $key )

Применение:

$f3->sync('SESSION'); // ensures PHP global var SESSION is the same as F3 variable SESSION

F3 автоматически синхронизирует следующие глобальные переменные PHP: GET , POST , COOKIE , REQUEST , SESSION , FILES , SERVER , ENV.

ref

Получение ссылки на ключ hive и его содержимое

mixed &ref ( string $key [, bool $add = true, mixed $var = null ] )

Применение:

$f3->set('name','John');
$b = &$f3->ref('name'); // $b is a reference to framework variable 'name' , not a copy
$b = 'Chuck'; // modifiying the reference updates the framework variable 'name'
echo $f3->get('name'); // Chuck

Вы также можете добавить несуществующие ключи hive, элементы массива и свойства объекта, если по умолчанию второй аргумент имеет значение true.

$new = &$f3->ref('newVar'); // creates new framework hive var 'newVar' and returns reference to it
$new = 'hello world'; // set value of php variable, also updates reference
echo $f3->get('newVar'); // hello world
 
$new = &$f3->ref('newObj->name');
$new = 'Sheldon';
echo $f3->get('newObj')->name; // Sheldon
echo $f3->get('newObj->name'); // Sheldon
echo $f3->get('newObj.name'); // Sheldon
 
$a = &$f3->ref('hero.name');
$a = 'SpongeBob';
// or
$b = &$f3->ref('hero'); // variable
$b['name'] = 'SpongeBob';  // becomes array with key 'name'
$my_array = $f3->get('hero');
echo $my_array['name']; // 'SpongeBob'

Если второй аргумент $add равен false, он просто возвращает содержимое ключа hive только для чтения. Это поведение используется в get (). Если ключ hive не существует, он возвращает NULL.

Используйте третий аргумент, если вы хотите найти ссылку в своем собственном массиве / объекте, а не в hive.

$fruitQty = ["Bananas"=>5, "Oranges"=>2, "Apples"=>42, "Mangos"=>1];
$apples = &$f3->ref("Apples", true, $fruitQty); // References $fruitQty["Apples"]
$apples = 10;
 
echo $fruitQty["Apples"]; // 10

exists

Возвращает true, если ключ hive установлен (или возвращает метку времени и TTL, если кэшировано)

bool exists ( string $key [, mixed &$val=NULL] )

Функция exists также проверяет кэш хранилища, когда ключ не найден в hive. Если ключ найден в кэше, метод возвращает array ( $timestamp, $ttl ).

Применение:

$f3->set('foo','value');
 
$f3->exists('foo'); // true
$f3->exists('bar'); // false, was not set above

Применение exists особенно полезно, когда глобальные переменные PHP автоматически синхронизируются с помощью F3 :

// Synched hive keys with PHP global variables
$f3->exists('COOKIE.userid');
$f3->exists('SESSION.login');
$f3->exists('POST.submit');

Примечание. Если вы проверите наличие ключа SESSION, сессия запустится автоматически.

Вы также можете использовать аргумент $val для получения ключа переменной в hive. Это может сэкономить дополнительный вызов get.

if ($f3->exists('foo',$value)) {
    echo $value; // bar
}

devoid

Возвращает TRUE, если ключ hive пуст и не кэширован.

bool devoid ( string $key )

Функция devoid проверяет, установлен-ли ключ в кэше, если ключ не был найден в hive.

Применение:

$f3->set('foo',' ');
$f3->set('bar',array());
$f3->set('baz',array(),10);
 
$f3->devoid('foo'); // true
$f3->devoid('bar'); // true
$f3->devoid('baz'); // false

clear

Очистка ключа в hive

void clear ( string $key )

Чтобы полностью удалить ключ hive и его значение из памяти:

$f3->clear('foobar');
$f3->clear('myArray.param1'); // removes key `param1` from array `myArray`

Если данный ключ улья был кэширован ранее, он также будет очищен из кэша.

Еще несколько специальных применений:

$f3->clear('SESSION'); // destroys the user SESSION
$f3->clear('COOKIE.foobar'); // removes a cookie
$f3->clear('CACHE'); // clears all cache contents

Примечание. Одновременная очистка всего содержимого кэша не поддерживается серверной частью кэш-памяти XCache.

mset

Установка нескольких переменных с использованием ассоциативного массива

void mset ( array $vars [, string $prefix = ' '  [, integer $ttl = 0 ]] )

Применение:

$f3->mset(
    array(
        'var1'=>'value1',
        'var2'=>'value2',
        'var3'=>'value3',
    )
);
 
echo $f3->get('var1'); // value1
echo $f3->get('var2'); // value2
echo $f3->get('var3'); // value3

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

$f3->mset(
    array(
        'var1'=>'value1',
        'var2'=>'value2',
        'var3'=>'value3',
    ),
    'pre_'
);
 
echo $f3->get('pre_var1'); // value1
echo $f3->get('pre_var2'); // value2
echo $f3->get('pre_var3'); // value3

Чтобы кэшировать все переменные, установите положительное числовое целочисленное значение $ttl в секундах.

hive

Вернуть все содержимое улья (hive) в виде массива

array hive ()

Применение:

printf ("A Busy Hive: 
%s
"
, var_export( $f3->hive(), true ) );

copy

Копирование содержимого одной переменной hive в другую

mixed copy ( string $src, string $dst )

Если $dst уже существует в hive, он просто перезаписывается.

Применение:

$f3->set('foo','123');
$f3->set('bar','barbar');
$bar = $f3->copy('foo','bar'); // bar = '123'
$bar = 456;
$f3->set('foo','789');
echo $f3->get('bar'); // '456'

concat

Объединить строку со строковой переменной в hive

string concat ( string $key, string $val )

Метод вернёт результат конкатенации.

Примечание. Если $key нет в hive, он автоматически создается.

Применение:

$f3->set('count', 99);
$f3->set('item', 'beer');
$text = $f3->concat('count', ' bottles of '.$f3->get('item'));
$text .= ' on the wall';
$f3->concat('wall', $f3->get('count')); // new 'wall' hive key is created
echo $f3->get('wall'); // 99 bottles of beer on the wall

flip

Поменять местами ключи и значения переменной массива в hive

array flip ( string $key )

Применение:

$f3->set('data', array(
    'foo1' => 'bar1',
    'foo2 '=> 'bar2',
    'foo3' => 'bar3',
));
$f3->flip('data');
 
print_r($f3->get('data'));
/* output:
Array
(
    [bar1] => foo1
    [bar2] => foo2
    [bar3] => foo3
)
*/

push

Добавить элемент в конец переменной-массива в hive

mixed push ( string $key, mixed $val )

Применение:

$f3->set('fruits',array(
    'apple',
    'banana',
    'peach',
));
$f3->push('fruits','cherry');
 
print_r($f3->get('fruits'));
/* output:
Array
(
    [0] => apple
    [1] => banana
    [2] => peach
    [3] => cherry
)
*/

pop

Удалить последний элемент переменной-массива в hive

mixed pop ( string $key )

Применение:

$f3->set('fruits',array(
	'apple',
	'banana',
	'peach'
));
$f3->pop('fruits'); // returns "peach"
 
print_r($f3->get('fruits'));
/* output:
Array
(
    [1] => apple
    [2] => banana
)
*/

unshift

Добавить элемент в начало переменной-массива в hive

mixed unshift ( string $key, string $val )
 

Применение:

$f3->set('fruits',array(
	'apple',
	'banana',
	'peach'
));
$f3->unshift('fruits','cherry');
 
print_r($f3->get('fruits'));
/* output:
Array
(
    [0] => cherry
    [1] => apple
    [2] => banana
    [3] => peach
)
*/

shift

Удалить первый элемент переменной-массива в hive

array|NULL shift ( string $key )

Возвращает сдвинутую влево переменную-массив из hive, или NULL, если переменная массива hive пуста или не является массивом.

Примечание : Все числовые ключи массива переменной массива hive будут изменены, чтобы начать отсчет с нуля, в то время как буквенные (текстовые) ключи не будут затронуты.

Пример:

$f3->set('fruits', array(
    'crunchy'=>'apples',
    '11'=>'bananas',
    '6'=>'kiwis',
    'juicy'=>'peaches'
));
$f3->shift('fruits'); // returns "apples"
print_r($f3->get('fruits'));
/* output:
Array
(
    [0] => bananas
    [1] => kiwis
    [juicy] => peaches
)
*/

merge

Объединить массив с переменной массива в hive

array merge ( string $key, array $src [, bool $keep = FALSE])
 

Вернуть результирующий массив слияния. (Не касается значения ключа улья)

Пример:

$f3->set('foo', array('blue','green'));
$bar = $f3->merge('foo', array('red', 'yellow'));
 
/* $bar now is:
array (size=4)
  [0] => string 'blue' (length=4)
  [1] => string 'green' (length=5)
  [2] => string 'red' (length=3)
  [3] => string 'yellow' (length=6)
*/

Когда параметр $keep имеет значение true, $key в hive так же обновляется.

extend

Расширяет переменную массива hive значениями по умолчанию из $src

array extend ( string $key, array $src [, bool $keep = FALSE])

Этот метод предоставляет простой способ добавить некоторые значения по умолчанию в массив:

$f3->set('settings',[
	'foo'=> 1,
	'bar'=> 'baz',
	'colors'=>[
		'blue'=>1,
		'green'=>2
	]
]);
$f3->set('defaults',[
	'foo'=>0,
	'zzz'=>2,
	'colors'=>[
		'red'=>3,
		'blue'=>4
	],
]);
$settings = $f3->extend('settings','defaults');
print_r($settings);
 
/*
Array (
    [foo] => 1
    [zzz] => 2
    [colors] => Array (
            [red] => 3
            [blue] => 1
            [green] => 2
        )
    [bar] => baz
)
*/

Кодирование и преобразование

fixslashes

Преобразование обратного слеша в обычный слеш

string fixslashes ( string $str )

Применение:

$filepath = __FILE__; // \www\mysite\myfile.txt
$filepath = $f3->fixslashes($filepath); // /www/mysite/myfile.txt

split

Разбор строки через запятую, точку с запятой или вертикальную черту в массив

array split ( string $str [, $noempty = TRUE ] )

Применение:

$data = 'value1,value2;value3|value4';
print_r($f3->split($data));
/* output:
Array
(
    [0] => value1
    [1] => value2
    [2] => value3
    [3] => value4
)
*/

Примечание: по умолчанию отфильтровываются пустые значения. Установите $noempty в FALSE, чтобы предотвратить такое поведение.

stringify

Преобразование выражения / значения PHP в сжатую экспортируемую строку

string stringify ( mixed $arg [, array $stack = NULL ] )

Эта функция позволяет преобразовать любое выражение PHP, значение, массив или любой объект в сжатую и экспортируемую строку. Урощённый вариант сериализации.

Пример с простым 2D-массивом:

$elements = array('water','earth','wind','fire');
$fireworks = array($elements, shuffle($elements), array_flip($elements));
echo $f3->stringify($fireworks);
// Outputs e.g.:
"[['water','earth','wind','fire'],true,['earth'=>0,'water'=>1,'wind'=>2,'fire'=>3]]"
$car = new stdClass();
$car->color = 'green';
$car->location = array('35.360496','138.727798');
echo $f3->stringify($car);
// Outputs e.g.:
"stdClass::__set_state(['color'=>'green','location'=>['35.360496','138.727798']])"

csv

Свести значения массива и вернуть как строку CSV

string csv ( array $args )

Применение:

$elements = array('water','earth','wind','fire');
echo $f3->csv($elements); // displays 'water','earth','wind','fire' // including single quotes

camelcase

Преобразование строки snake_case в camelCase

string camelcase ( string $str )

Применение:

$str_s_c = 'user_name';
$f3->camelcase($str_s_c); // returns 'userName'

snakecase

Преобразование строки camelCase в snake_case

string snakecase ( string $str )

Применение:

$str_CC = 'userName';
$f3->snakecase($str_CC); // returns 'user_name'

sign

Возвращает -1, если указанное число отрицательное, 0, если ноль, или 1, если число положительное.

int sign ( mixed $num )

hash

Сгенерировать хеш 64-бит / base36

string hash ( string $str )

Создает хеш для заданной строки (длиной от 11 до 13 символов)

Пример:

$f3->hash('foobar'); // returns '3vrllw03cko4s' (length=13)

base64

Шифрование данных в кодировке Base64

string base64 ( string $data, string $mime )

Пример:

echo $f3->base64('

foobar

'
,'text/html'); // data:text/html;base64,PGgxPmZvb2JhcjwvaDE+

encode

Преобразование специальных символов в объекты HTML

string encode ( string $str )

Кодирует такие символы, как & и другие символы, в зависимости от настройки ENCODING вашего приложения. (по умолчанию: UTF-8)

Пример:

echo $f3->encode("we want 'sugar & candy'");
// we want 'sugar & candy'

decode

Преобразование специальных HTML-объектов обратно в символы

string decode ( string $str )

Пример:

echo $f3->decode("we want 'sugar & candy'");
// we want 'sugar & candy'

clean

Удаляет HTML-теги (кроме перечисленных в аргументе) и непечатаемые символы для предотвращения атак XSS / внедрения кода.

string clean ( mixed $var [, string $tags = NULL ] )

$var может быть либо string либо array. В последнем случае он будет рекурсивно пройден для очистки каждого элемента.

$tags определяет перечень из разрешенных HTML тегов, которые не будут удалены.

Совет : рекомендуется использовать эту функцию для очистки введенных данных формы.

Примеры:

$foo = "99 bottles of beer on the wall. ";
echo $f3->clean($foo); // "99 bottles of beer on the wall. alert('scripty!')"
$foo = "

nice news article headline

"
; $h1 = $f3->clean($foo,'h1,span'); //

nice news article headline

scrub

Аналог clean (), за исключением того, что переменная передается по ссылке

string scrub ( mixed &$var [, string $tags = NULL ] )

Пример:

$foo = "99 bottles of beer on the wall. ";
$bar = $f3->scrub($foo);
echo $foo; // 99 bottles of beer on the wall. alert('scripty!')

serialize

Вернуть строковое представление любого значения PHP

string serialize ( mixed $arg )

В зависимости от системной переменной SERIALIZER этот метод преобразует что угодно в строковое выражение. Возможные значения: igbinary и php. F3 проверяет при запуске, доступен ли igbinary, и устанавливает его приоритет, поскольку расширение igbinary работает намного быстрее и использует меньше дискового пространства для сериализации.

unserialize

Возвращает значение PHP, полученное из сериализованной строки

string unserialize ( mixed $arg )

Локализация

Примечание: F3 следует правилам форматирования ICU, не требуя модуля PHP intl .

format

Возврат форматированной строки с учетом локали

string format( string $format [, mixed $arg0 [, mixed $arg1...]] )

Строка $format содержит один или несколько заполнителей и идентифицируются с помощью индекса позиции, заключенного в фигурных скобках, начальный индекс является 0.

echo $f3->format('Name: {0} - Age: {1}','John',23); //outputs the string 'Name: John - Age: 23'

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

Текущие поддерживаемые типы:

  • дата

  • дата, короткая

  • дата, длинная

  • дата, произвольная, {exp}

  • время

  • время, короткое

  • время, произвольное, {exp}

  • число, целое число

  • число, валюта

  • число, валюта, целое

  • число, валюта, {char}

  • число, процент

  • число, десятичное, {int}

  • множественное число, {exp}

echo $f3->format('Current date: {0,date} - Current time: {0,time}',time());
//outputs the string 'Current date: 04/12/2013 - Current time: 11:49:57'
echo $f3->format('Created on: {0,date,custom,%A, week: %V }', time());
//outputs the string 'Created on: Monday, week 45'
echo $f3->format('{0} is displayed as a decimal number while {0,number,integer} is rounded',12.54);
//outputs the string '12.54 is displayed as a decimal number while 13 is rounded'
echo $f3->format('Price: {0,number,currency}',29.90);
//outputs the string 'Price: $29.90'
echo $f3->format('Percentage: {0,number,percent}',0.175);
//outputs the string 'Percentage: 18%' //Note that the percentage is rendered as an integer
echo $f3->format('Decimal Number: {0,number,decimal,2}', 0.171231235);
//outputs the string 'Decimal Number: 0,17'

Синтаксис множественного типа должен начинаться с 0, plural, за которым следует список ключевых слов множественного числа, связанных с желаемым выводом. Допустимые ключевые слова: «* ноль *», «* один *», «* два *» и «* другой *».

Кроме того, вы можете вставить соответствующую цифру в выходные строки с помощью символа #, который будет автоматически заменен соответствующим числом, как показано в примере ниже:

$cart_dialogs= '{0, plural,'.
	'zero	{Your cart is empty.},'.
	'one	{One (#) item in your cart.},'.
	'two	{A pair of items in your cart.},'.
	'other	{There are # items in your cart.}
}';
 
echo $f3->format($cart_dialogs,0); // displays 'Your cart is empty.'
echo $f3->format($cart_dialogs,1); // displays 'One (1) item in your cart.'
echo $f3->format($cart_dialogs,2); // displays 'A pair of items in your cart.'
echo $f3->format($cart_dialogs,3); // displays 'There are 3 items in your cart.'

Каждое ключевое слово во множественном числе является необязательным, и вы можете, например, опустить ключевое слово во множественном числе «два», если ключевое слово «другой» подходит для этого случая. Конечно, если вы опустите их все, будут отображаться только цифры.

Автоматическое форматирование переменных hive

Фреймворк позволяет для вашего удобства, и упрощения использования форматирования в ваших шаблонах, извлекать и форматировать переменные из hive с помощью одной команды:

Пример:

$f3->set('a_books_story',
	'{0, plural,'.
		'zero	{There is n#thing on the table.},'.
		'one	{A book is on the table.},'.
		'two	{Two (#) books are on this table.},'.
		'other	{There are # books on the table.}'.
	'}'
);
echo $f3->get('a_books_story',0); // displays 'There is n0thing on the table.'
echo $f3->get('a_books_story',1); // displays 'A book is on the table.'
echo $f3->get('a_books_story',2); // displays 'Two (2) books are on this table.'
echo $f3->get('a_books_story',7); // displays 'There are 7 books on the table.'

language

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

string language ( string $code )

Эта функция используется при загрузке F3 для автоматического определения языка пользователя, просматривая заголовки HTTP-запроса, в частности заголовок Accept-Language, отправленный браузером.

Используйте системную переменную LANGUAGE для получения и установки языков, поскольку она также обрабатывает зависимости, такие как установка локалей с помощью php setlocale (LC_ALL, …) и изменение файлов словарей. Переменная FALLBACK определяет язык по умолчанию, который будет использоваться, если ни один из обнаруженных языков не доступен в качестве файла словаря.

Пример:

$f3->get('LANGUAGE'); // 'de-DE,de,en-US,en'
$f3->set('LANGUAGE', 'es-BR,es');
$f3->get('LANGUAGE'); // 'es-BR,es,en' the fallback language is added at the end of the list

Переменная LANGUAGE принимает тот же тип строки, что и заголовок HTTP Accept-Language, который представляет собой список разделенных запятыми двухбуквенных языковых кодов, за которыми, возможно, следуют символ и двухбуквенный код страны.

Примечание. Даже если в локали POSIX в качестве разделителя используется символ подчеркивания (es_BR.UTF-8), вы должны определить переменную LANGUAGE с дефисом (es-BR). Файлы словарей подчиняются тому же правилу (es-BR.php / es-BR.ini).

Системные локали

Чтобы гарантировать, что метод форматирования и другие функции php, учитывающие языковой стандарт, работали должным образом, языковой стандарт системы загружается автоматически этой функцией. Например:

$f3->set('ENCODING','UTF-8');
$f3->set('LANGUAGE','it-IT');// the locale it_IT.UTF-8 will be automatically loaded using setlocale

Еще несколько примеров:

$f3->LANGUAGE='en' => F3 will try to load 2 locales:
    en.UTF-8
    en
$f3->LANGUAGE='en-US' => F3 will try to load 4 locales:
    en_US.UTF-8
    en_US
    en.UTF-8
    en
$f3->LANGUAGE='en-US,en-GB' => F3 will try to load 6 locales:
    en_US.UTF-8
    en_US
    en_GB.UTF-8
    en_GB
    en.UTF-8
    en

На заметку: загружается первая локаль, найденная на сервере. Убедитесь, что на вашем сервере установлены все языковые стандарты, которые вы хотите поддерживать в своем приложении. На большинстве компьютеров с Linux вы можете проверить это с помощью locale,и установить новые языковые стандарты с помощью dpkg-reconfigure locales. Некоторым конфигурациям веб-сервера apache может потребоваться перезагрузка впоследствии для работы с новыми языковыми стандартами.

lexicon

Перенести словарные записи в hive

array lexicon ( string $path )

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

$f3->set('LOCALES','dict/');

Файл словаря может быть файлом php, возвращающим парный ассоциативный массив «ключ-значение», или файлом конфигурации в формате .ini.

Маршрутизация

alias

Сборка URL из псевдонима

string alias ( string $name [, array|string $params = array() [, array|string $query = array() ]] )

Пример:

$f3->route('GET @complex:/resize/@format/*/sep/*','App->nowhere');
$f3->alias('complex','format=20x20,2=foo/bar,3=baz.gif');
$f3->alias('complex',array('format'=>'20x20',2=>'foo/bar',3=>'baz.gif'));
// Both examples return '/resize/20x20/foo/bar/sep/baz.gif'

build

Заменяет токенизированный URL на значениями токена текущего маршрута

string build ( string $url [, array $params = array() ] )

Пример:

// for instance the route is '/subscribe/@channel' with PARAMS.channel = 'fatfree'
 
echo $f3->build('@channel'); // displays 'fatfree'
echo $f3->build('/get-it/now/@channel'); // displays '/get-it/now/fatfree'
echo $f3->build('/subscribe/@channel');  // displays '/subscribe/fatfree'

Если вы хотите конкретно определить токены в данном $url, вы можете использовать $params:

$f3->build('/resize/@format/*/sep/*',array(
  'format'=>'200x200',// 1=>'200x200' also works
  2=>'foo/bar',
  3=>'baz.gif'
));
// returns: /resize/200x200/foo/bar/sep/baz.gif

mock

Имитация HTTP-запроса

mixed mock ( string $pattern [, array $args = NULL [, array $headers = NULL [, string $body = NULL ]]] )

Функция имитирует HTTP-запрос на основе команды и ресурса, определенных в $pattern.

  • $args экспортируется как глобальная переменная соответствующего метода ( $_GET, $_POST или $_REQUEST)

  • $headers экспортируется как глобальные заголовки HTTP ( $_SERVER[HTTP_…])

  • Тело HTTP-запроса $body экспортируется как BODY переменная в HIVE для методов, не равных GET или HEAD. Если $body не определено, $args кодируется и экспортируется как BODY

  • Добавление [ajax]к $pattern фиктивным вызовам AJAX

  • Добавление [sync]к $pattern обычных (синхронных) вызовов

  • Добавление [cli] к $pattern имитирующим вызовам командной строки (CLI)

  • Именованные маршруты и токены являются допустимыми ресурсами

Базовый пример использования:

$f3->mock('GET /page/view [ajax]');

Базовый пример использования с именованным маршрутом и токеном:

$f3->route('GET @grub:/food/@id', /* … */);
$f3->mock('GET @grub(@id=bread)');

Тест как расширенный пример использования:

$f3->route('GET|POST|PUT @grub:/food/@id/@quantity', /* … */);
$f3->mock('POST /food/sushki/134?a=1',array('b'=>2));
$test->expect(
	$_GET==array('a'=>1) && $_POST==array('b'=>2) && $_REQUEST==array('a'=>1,'b'=>2) && $f3->get('BODY')=='b=2',
	'Request body and superglobals $_GET, $_POST, $_REQUEST correctly set on mocked POST'
);

parse

Парсит строку, содержащую пары ключ-значение, и использует их в качестве токенов маршрутизации.

NULL parse ( string $str )

Пример:

$f3->parse('framework=f3 , speed=fast , features=full');
echo $f3->get('PARAMS.framework');  // 'f3'
echo $f3->get('PARAMS.speed');      // 'fast'

route

Привязать шаблон маршрута к данному обработчику

null route ( string|array $pattern, callback $handler [, int $ttl = 0 [, int $kbps = 0 ]] )

Базовый пример использования:

$f3->route('POST /login','AuthController->login');

Схема маршрута

Переменная $pattern описывает образец маршрута, который состоит из типа запроса(ов) и запрос URI, оба разделенных пробелом символ.

Verbs

Возможные определения типа запроса (Verb), которые будет обрабатывать F3: GET , POST , PUT , DELETE , HEAD , PATCH , CONNECT .

Вы можете комбинировать несколько методов запросов, чтобы использовать один и тот же обработчик маршрута для всех из них. Просто разделите их вертикальной чертой, например GET|POST.

Токены

URI запроса может содержать один или несколько токенов, предназначенных для определения динамических маршрутов. Токены обозначаются символом @ перед их именем и могут быть заключены в одиночные фигурные скобки { }. Смотрите эти примеры:

$f3->route('GET|HEAD /@page','PageController->display'); // ex: /about
$f3->route('POST /@category/@thread','ForumThread->saveAnswer'); // /games/battlefield3
$f3->route('GET /image/@width-@height/@file','ImageCompressor->render'); // /image/300-200/mario.jpg
$f3->route('GET /image/{@width}x{@height}/@file','ImageCompressor->render'); // /image/300x200/mario.jpg

После обработки URI входящего запроса (инициированного запросом) вы найдете значение каждого из этих токенов в системной переменной PARAMS как именованный ключ, например $f3→get('PARAMS.file'). / / 'mario.jpg'

Примечание. Маршруты и соответствующие им типы запросов сгруппированы по шаблону URL. Статические маршруты предшествуют маршрутам с динамическими токенами или подстановочными знаками.

Wildcards

Вы также можете определить подстановочные знаки (wildcards) ( /*) в своем URI маршрутизации. Кроме того, вы можете использовать их в сочетании с токенами.

$f3->route('GET /path/*/@page', function($f3,$params) {
    // called URI: "/path/cat/page1"
    // $params is the same as $f3->get('PARAMS');
    $params[0]; // contains the full route path. "/path/cat/page"
    $params[1]; // and further numeric keys in PARAMS hold the catched wildcard paths and tokens. in this case "cat"
    $params['page']; // is your last segment, in this case "page1"
});

Примечание: переменная `PARAMS` содержит все токены в качестве именованного ключа и, кроме того, все токены и подстановочные знаки в качестве числового ключа, в зависимости от их порядка появления.

Маршрут выше также работает с подкатегориями. Пример вызова: /path/cat/subcat/page1

$params[1]; // now contains "/cat/subcat"

Он так же работает с несколькими подуровнями. Вам просто нужно отделить значение с помощью разделителя / для обработки ваших подкатегорий. Например: /path/*/@pagetitle/@pagenum

Задача усложняется, когда вы пытаетесь использовать более одного подстановочного знака, потому что только первый /* - может содержать неограниченное количество сегментов пути. Любые другие подстановочные знаки могут содержать только одну часть между слешем ( /).

Группы

Можно назначить несколько маршрутов одному обработчику маршрутов, используя массив маршрутов в $pattern. Это выглядело бы так:

$f3->route(
  array(
    'GET /archive',
    'GET /archive/@year',
    'GET /archive/@year/@month',
    'GET /archive/@year/@month/@day'
  ),
  function($f3,$params){
	$params+=array('year'=>2013,'month'=>1,'day'=>1); //default values
    //etc..
  }
);
Именованные маршруты

Вы можете присвоить имена своим маршрутам:

$f3->route('GET @beer_list: /beer', 'Beer->list');

Имена вставляются после типа маршрута (GET) и им предшествует символ @. Ко всем именованным маршрутам можно получить доступ с помощью системной переменной ALIASES для дальнейшей обработки в шаблонах или для перенаправления.

Кроме того, вы можете использовать существующее имя маршрута, чтобы сократить дополнительные определения маршрута:

$f3->route('GET @beer_details: /beer/@id', 'Beer->get');
$f3->route('POST @beer_details', 'Beer->saveComment');
$f3->route('PUT @beer_details', 'Beer->savePhoto');

Route Handler

Может быть вызываемым метод класса, например Foo→bar или Foo::bar, именем функции или анонимной функцией.

F3 автоматически передает экземпляр F3 и токены маршрута классам контроллера обработчика маршрутов. Например:

$f3->set('hello','world');
$f3->route('GET /foo/@file','Bar->baz');
 
class Bar {
    function baz($f3,$args) {//
        echo $f3->get('hello');
        echo $args['file'];
    }
}

Кэширование

Третий аргумент $ttl определяет время кэширования в секундах. Установка для этого аргумента положительного значения вызовет функцию истечения срока действия для установки метаданных кэша в заголовке ответа HTTP. Он также кэширует ответ маршрута, но кэшируются только запросы GET и HEAD.

Если CACHE отключен, $ttl будет управлять кэшем браузера только с использованием метаданных заголовка с истекшим сроком действия. Если CACHE включен и $ttl для текущего обработчика URI запроса установлено в положительное значение, F3 дополнительно кэширует вывод для этой страницы и обновляет его $ttl по истечении срока действия.

Регулирование полосы пропускания

Установите 4-й аргумент $kbps на желаемое ограничение скорости, чтобы включить регулирование полосы пропускания.

reroute

Перенаправление на указанный URI

null reroute ( [ string|array $url = NULL [, bool $permanent = FALSE [, bool $die = TRUE ]]] )

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

// an old page is moved permanently
$f3->route('GET|HEAD /obsoletepage', function($f3) {
    $f3->reroute('/newpage', true);
});
 
// whereas a Post/Redirect/Get pattern would just redirect temporarily
$f3->route('GET|HEAD /login', 'AuthController->viewLoginForm');
$f3->route('POST /login', function($f3) {
    if( AuthController->checkLogin == true )
        $f3->reroute('/members', false);
    else
        $f3->reroute('/login', false);
});
 
// if no $url parameter is set, it'll reroute to the current route with GET verb
$f3->route('POST /search', function($f3) {
    // back to search form, if an empty term was submitted
    if ($f3->devoid('POST.search_term'))
        $f3->reroute();
});
 
// we can also reroute to external URLs
$f3->route('GET /partners', function($f3) {
    $f3->reroute('http://externaldomain.com');
});
 
// it's also possible to reroute to named routes
$f3->route('GET @beer_list: /beer', 'Beer->list');
$f3->route('GET /old-beer-page', function($f3) {
    $f3->reroute('@beer_list');
});
 
// even with dynamic parameter in your named route
$f3->route('GET @beer_producers: /beer/@country/@village', 'Beer->byproducer');
$f3->route('GET /old-beer-page', function($f3) {
    $f3->reroute('@beer_producers(@country=Germany,@village=Rhine)');
});
// but it'll also work with any unnamed tokenized URL
$f3->reroute('/beer/@country/@village',TRUE)
 

Когда $url является массивом, он используется для перенаправления псевдонима. Вы можете указать псевдоним в 1-м элементе массива, его параметры во 2-м и дополнительные элементы запроса как 3-й элемент массива:

$f3->reroute(['filter','a=foo,b=bar','time=3']);
// or
$f3->reroute(['filter',['a'=>'foo','b'=>'bar'],['time'=>3]]);
 
// equivalent to:
$f3->reroute('@filter(a=foo,b=bar)?time=3');

Параметр $die может быть использован для отключения немедленного перенаправления, а сценарий продолжается после установки соответсвующих заголовков. Это может быть полезно для тестирования.

redirect

Перенаправить маршрут на другой URL

null redirect ( string|array $pattern, string $url [, bool $permanent = TRUE ] )

Это небольшой метод предназначен только для перенаправления клиента. Аргумент $pattern принимает то же значение, как метод route().

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

// redirect old pages
$f3->redirect('GET /oldpage', '/newpage');
// jump to absolut URLs
$f3->redirect('GET /external-link', 'http://subdomain.domain.com');
// temporarily redirect to another named route
$f3->redirect('GET /login', '@member_area', false);
// redirect one named route to another
$f3->redirect('GET @member_welcome', '@member_area');

Перенаправления можно настроить в файлах конфигурации в [redirects] сегменте.

map

Предоставить интерфейс ReST путем сопоставления HTTP-метода с методом класса

null map ( string $url, string $class [, int $ttl = 0 [, int $kbps = 0 ]] )

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

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

$f3->map('/news/@item','News');
 
class News {
    function get() {}
    function post() {}
    function put() {}
    function delete() {}
}

run

Сопоставление маршрутов с входящим URI и вызов их обработчиков маршрута

null run ()

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

$f3 = require __DIR__.'/lib/base.php';
$f3->route('GET /',function(){
    echo "Hello World";
});
$f3->run();

После обработки URI входящего запроса шаблон маршрутизации, который соответствует этому URI, сохраняется в переменной PATTERN, текущий URI HTTP-запроса в URI и метод запроса в VERB. В PARAMS будут содержаться все токены как именованные ключи, а также все токены и подстановочные знаки как числовые ключи, в зависимости от их порядка появления.

Генерируется ошибка 404, если токенизированный класс не существует.

Примечание. Если шаблон статического и динамического маршрута соответствует текущему URI, то шаблон статического маршрута имеет приоритет.

call

Выполнить callback / хук (поддерживает формат 'класс→ метод')

mixed|false call ( callback $func [, mixed $args = NULL [, string $hooks = '' ]] )

Этот метод предоставляет возможность вызывать коллбеки и их аргументы. F3 распознает их как действительные обратные вызовы:

  • Анонимные / лямбда-функции (также известные как замыкания)

  • array('class','method')

  • class::method статический метод

  • class→method эквивалентно array(new class,method)

$args если указано, предоставляет средства для выполнения обратного вызова с параметрами.

$hooks используется в route() для указания функций до и после выполнения, т.е. beforeroute() и afterroute().

chain

Последовательно выполнять указанные обратные вызовы; Применяйте одинаковые аргументы ко всем обратным вызовам

array chain ( array|string $funcs [, mixed $args = NULL ] )

Этот метод последовательно вызывает несколько обратных вызовов:

echo $f3->chain('a; b; c', 0);
 
function a($n) {
	return 'a: '.($n+1); // a: 1
}
 
function b($n) {
	return 'b: '.($n+1); // b: 1
}
 
function c($n) {
	return 'c: '.($n+1); // c: 1
}

relay

Последовательно выполнять указанные коллбеки; Ретранслировать результат предыдущего коллбека в качестве аргумента для следующего

array relay ( array|string $funcs [, mixed $args = NULL ] )

Этот метод вызывает коллбек последовательно, как цепочку, но применяет результат первой функции в качестве аргумента последующей функции, то есть:

echo $f3->relay('a; b; c', 0);
 
function a($n) {
	return 'a: '.($n+1); // a: 1
}
 
function b($n) {
	return 'b: '.($n+1); // b: 2
}
 
function c($n) {
	return 'c: '.($n+1); // c: 3
}

Файловая система

copy

Собственная функция PHP

bool copy ( string $source , string $dest [, resource $context ] )

Чтобы скопировать файл, используйте встроенную функцию PHP copy(). Приведено в данном руководстве для удобства.

Собственная функция PHP

bool unlink ( string $filename [, resource $context ] )
 

Чтобы удалить файл, используйте встроенную функцию PHP unlink(). Приведено в данном руководстве для удобства.

rename

Собственная функция PHP

bool rename ( string $oldname , string $newname [, resource $context ] )
 

Чтобы переместить файл, используйте встроенную функцию PHP rename(), изменив путь во втором аргументе. Приведено в данном руководстве для удобства.

mutex

Создать мьютекс, вызвать коллбек и освободить ресурс по его завершению

mixed mutex ( string $id, callback $func [, mixed $args = NULL ] )

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

$f3->mutex('test',function() {
	// Critical section
	session_start();
	$contents=file_get_contents('mutex');
	sleep(5);
	file_put_contents('mutex',$contents.date('r').' '.session_id()."\n");
});

В коллбек можно передать аргументы:

$f3->mutex('my-mutex-id',function($path,$str) {
	@file_put_contents($path,$str);
},array('/foo/bar/facts.txt','F3 is cool'));

read

Прочитать файл (с возможностью применения Unix LF в качестве символа окончания строки)

string|FALSE read ( string $file [, bool $lf = FALSE ] )

Использует функцию PHP file_get_contents() для чтения всего файла и возврата в виде строки. Возвращает true/false в зависимости от результата попытки чтения файла. Преобразует любые символы окончания строки в LF.

rel

Возвращает путь относительно базового каталога

string rel ( string $url )

Пример:

$f3->set('BASE','http://fatfreeframework.com/');
echo $f3->rel( 'http://fatfreeframework.com/gui/img/supported_dbs.jpg' ); // 'gui/img/supported_dbs.jpg'

write

Эксклюзивная запись в файл

int|FALSE write ( string $file, mixed $data [, bool $append = FALSE ] )

Использует функцию PHP file_put_contents() с флагом LOCK_EX для блокировки файла во время записи.

Если $append установить в TRUE и $file уже существовал на момент вызова метода, то $data добавляется к содержимому файла вместо того чтобы перезаписать содержимое файла.

type

В JSON схеме доступны следующие семь примитивных типов:

  • string — строковое значение.
  • null — значение null.
  • number — Любое число. Эквивалент float в PHP.
  • integer — Целое число. float не допускается.
  • boolean — значение true/false.
  • array — Список значений. Эквивалент массива в JavaScript. В PHP соответствует массиву с числами в ключах или массиву без указанных ключей.
  • object — Пары ключ => значение. Эквивалент объекта в JavaScript. В PHP соответствует ассоциативному массиву (массиву с ключами).

Примитивный тип указывается в type элементе массива. Например:

array(
	'type' => 'string',
);

JSON схема позволяет указать сразу несколько типов:

array(
	'type' => [ 'boolean', 'string' ],
);
меню

Преобразование типов

REST API WordPress принимает данные в GET или POST запросе, поэтому данные нужно преобразовать. Например некоторые строковые значения нужно превратить в их реальные типы.

  • string — этот тип должен пройти проверку is_string().
  • null — значение должно быть реальным null. Это означает, что отправка null значения в URL-адресе или в виде закодированного в форме URL тела сообщения невозможна, необходимо использовать тело запроса JSON.
  • number — число или строка, которая пройдет проверку is_numeric(). Значение будет преобразовано во (float).
  • integer — Целые числа или строки без дробной части. Значение будет преобразовано во (int).
  • boolean — Логические true/false. Числа или строки 0, 1, '0', '1', 'false', 'true'. 0 это false. 1 это true.
  • array — Индексный массив соответствующий wp_is_numeric_array() или строка. Если передана строка, то значения разделенные запятыми станут значениями элементов массива. Если запятых в строке нет, то значение станет первым элементом массива. Например: 'red, yellow' превратится в array( 'red', 'yellow' ), а 'blue' станет array( 'blue' ).
  • object — Массив, объект stdClass, объект применяемый JsonSerializable или пустая строка. Значения будут преобразованы в PHP массив.

При использовании нескольких типов, типы будут обрабатываться в указанном порядке. Это может повлиять на результат очистки. Например для 'type' => [ 'boolean', 'string' ] отправленное значение '1' превратиться в логическое true. Однако, если поменять порядок, то значение будет строка '1'.

Спецификация JSON схемы позволяет определять схемы без поля type. Но в WordPress этот параметр должен быть указан, иначе вы получите заметку _doing_it_wrong().

меню

string

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

minLength / maxLength

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

Например для следующей схемы ab, abc, abcd пройдут проверку, а a и abcde нет.

array(
	'type' => 'string',
	'minLength' => 2,
	'maxLength' => 4,
);

format

Если указать этот аргумент, то значения параметра переданного в REST будут проверятся на соответствие указанному формату.

Возможные варианты параметра:

  • date-time — дата в формате RFC3339. см. rest_parse_date()
  • uri — uri в соответствии с esc_url_raw().
  • email — См. is_email().
  • ip — v4 или v6 ip адрес. См. rest_is_ip_address()
  • uuid — uuid код любой версии. См. wp_is_uuid()
  • hex-color — 3 или 6 символов hex цвета в префиксом #. См. rest_parse_hex_color().

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

array(
	'type'   => 'string',
	'format' => 'date-time',
);

Важно: значение параметра должно соответствовать указанному формату всегда, поэтому оно не может быть пустой строкой. Если нужна возможность указать пустую строку, то нужно добавить тип null.

Например, следующая схема разрешит указать IP (127.0.0.1) или не указывать значение параметра:

array(
	'type'   => [ 'string', 'null' ],
	'format' => 'ip',
);

Код из ядра, который показывает как конкретно работает этот параметр:

// This behavior matches rest_validate_value_from_schema().
if ( isset( $args['format'] )
	&& ( ! isset( $args['type'] ) || 'string' === $args['type'] || ! in_array( $args['type'], $allowed_types, true ) )
) {
	switch ( $args['format'] ) {
		case 'hex-color':
			return (string) sanitize_hex_color( $value );

		case 'date-time':
			return sanitize_text_field( $value );

		case 'email':
			// sanitize_email() validates, which would be unexpected.
			return sanitize_text_field( $value );

		case 'uri':
			return esc_url_raw( $value );

		case 'ip':
			return sanitize_text_field( $value );

		case 'uuid':
			return sanitize_text_field( $value );
	}
}

Обратите внимание, что format обрабатывается не обязательно только тогда когда type = string. format будет применяться если:

  • type = string.
  • type отличается от стандартного примитивного типа.
  • type не указан (но в WP это запрещено).
меню

pattern

Используется для проверки соответствия значения строкового параметра указанному регулярному выражению.

Например, для следующей схемы, #123 подходит, а #abc нет:

array(
	'type'    => 'string',
	'pattern' => '#[0-9]+',
);

Модификаторы регулярных выражений не поддерживаются, т.е. нельзя указать /i, чтобы не зависеть от регистра.

RFC схемы JSON рекомендует ограничиться следующими функциями регулярных выражений, чтобы схема была совместима с как можно большим количеством различных языков программирования:

  • Разрешены отдельные символы Юникод соответствующие JSON спецификации [RFC4627].
  • Простая группа и диапазон символов: [abc] и [a-z].
  • Простая группа и диапазон исключающих символов: [^abc], [^a-z].
  • Просты квантификаторы: * (ноль или более), + (один или более), ? (один или ничего), и их «ленивые» версии: +?, *?, ??.
  • Квантификаторы диапазона: {x} (x раз), {x,y} (от x до y раз), {x,} (x и более раз), и их «ленивые» версии.
  • Анкоры начала и конца строки: ^, $.
  • Просты группы (...) и чередование |.

Шаблон должен быть совместим с диалектом регулярных выражений ECMA 262.

меню

null

Значение должно быть реальным null. Это означает, что отправка null значения в URL-адресе или в виде закодированного в форме URL тела сообщения невозможна, необходимо использовать тело запроса JSON.

boolean

Логические true/false. Можно запросе можно указать числа или строки:

  • true — 1, '1', 'true'.
  • false — 0, '0', 'false'.

Подробнее о том, как обрабатывается переданное значение смотрите в коде функции: rest_sanitize_boolean().

number / integer

Числа имеют тип number (любое число, может быть дробным) или integer (только целые числа):

if ( 'integer' === $args['type'] ) {
	return (int) $value;
}

if ( 'number' === $args['type'] ) {
	return (float) $value;
}

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

minimum / maximum

Ограничивает диапазон допустимых чисел (включая сами числа). Например, 2 подойдет под схему ниже, а 0 и 4 - нет:

array(
	'type' => 'integer',
	'minimum' => 1,
	'maximum' => 3,
);

exclusiveMinimum / exclusiveMaximum

Это дополнительные параметры для minimum / maximum, которые отключают «включительную» проверку. Т.е. значение НЕ может равняться определенному минимуму или максимуму а должно быть больше или меньше, но не равно.

Например, в следующем случае приемлемым значением будет только 2:

array(
	'type'             => 'integer',
	'minimum'          => 1,
	'exclusiveMinimum' => true,
	'maximum'          => 3,
	'exclusiveMaximum' => true,
);

multipleOf

Утверждает кратность числа, т.е. полученное значение должно нацело делиться на указанное в этом параметре число.

Например, следующая схема будет принимать только четные целые числа:

array(
	'type'       => 'integer',
	'multipleOf' => 2,
);

Также есть поддержка десятичных дробей. Например, следующая схема может быть использована для приема процента с максимальным значением одна десятая:

array(
	'type'       => 'number',
	'minimum'    => 0,
	'maximum'    => 100,
	'multipleOf' => 0.1,
);

array

Указывает что должен быть передан массив. Смотрите: rest_sanitize_array().

items

Устанавливает формат каждого элемента в массиве. Для этого нужно использовать параметр items, в котором нужно указать JSON схему каждого элемента массива.

Например, следующая схема требует массив IP-адресов:

array(
	'type'  => 'array',
	'items' => array(
		'type'   => 'string',
		'format' => 'ip',
	),
);

Для такой схемы эти данные пройдут проверку:

[ "127.0.0.1", "255.255.255.255" ]

А эти нет:

[ "127.0.0.1", 5 ]

Схема items может быть любой, в том числе и схемой вложенного массива:

array(
	'type'  => 'array',
	'items' => array(
		'type'  => 'array',
		'items' => array(
			'type'   => 'string',
			'format' => 'hex-color',
		),
	),
);

Для такой схемы эти данные пройдут проверку:

[
  [ "#ff6d69", "#fecc50" ],
  [ "#0be7fb" ]
]

А эти не пройдут:

[
  [ "#ff6d69", "#fecc50" ],
  "george"
]

меню

minItems / maxItems

Используется для ограничения минимального и максимального количества элементов массива (включительно).

Например, следующая схема пропустит данные [ 'a' ] и [ 'a', 'b' ], но не пропустит
[] и [ 'a', 'b', 'c' ]:

array(
	'type'     => 'array',
	'minItems' => 1,
	'maxItems' => 2,
	'items'    => array(
		'type' => 'string',
	),
);

uniqueItems

Используется когда нужно, чтобы значения массива были уникальны. Смотрите: rest_validate_array_contains_unique_items().

Например, следующая схема посчитает правильными данные [ 'a', 'b' ], и не правильными [ 'a', 'a' ]:

array(
	'type'        => 'array',
	'uniqueItems' => true,
	'items'       => array(
		'type' => 'string',
	),
);
Важно знать об уникальности значений.
  • Значения разных типов рассматриваются как уникальные. Например, '1', 1 и 1.0 — это разные значения.

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

    [
      [ "a", "b" ],
      [ "b", "a" ]
    ]
  • При сравнении объектов, порядок определения свойств НЕ имеет значения. Например у такого массив объекты будут считаться одинаковыми:

    [
      {
    	"a": 1,
    	"b": 2
      },
      {
    	"b": 2,
    	"a": 1
      }
    ]
  • Уникальность проверяется рекурсивно для значений массивов в обеих функциях: rest_validate_value_from_schema() и rest_sanitize_value_from_schema(). Нужно это для того чтобы не было моментов, когда items могут быть уникальными до очистки и одинаковыми после.

    Возьмем для примера такую схему:

    array(
    	'type' => 'array',
    	'uniqueItems' => true,
    	'items' => array(
    		'type' => 'string',
    		'format' => 'uri',
    	),
    );

    Такой запрос прошёл бы проверку потому что строки разные:

    [ "https://site.com/hello world", "https://site.com/hello%20world" ]

    Однако после обработки функцией esc_url_raw() строки станут одинаковые.

    В этом случае rest_sanitize_value_from_schema() вернула бы ошибку. Поэтому вам всегда следует проверить и очищать параметры.

меню

object

Этот тип требует, чтобы принимаемые данные были объектом. Также нужно указать формат каждого свойства объекта в параметре properties.

См. rest_sanitize_object().

properties

Обязательные свойства объекта. Для каждого свойства указывается своя схема.

Например, следующая схема требует объект, где свойство name является строкой, а color шестнадцатеричным цветом.

array(
	'type'       => 'object',
	'properties' => array(
		'name'  => array(
			'type' => 'string',
		),
		'color' => array(
			'type'   => 'string',
			'format' => 'hex-color',
		),
	),
);

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

{
  "name": "Primary",
  "color": "#ff6d69"
}

А такие не пройдет:

{
  "name": "Primary",
  "color": "orange"
}
Обязательные свойства

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

Есть два способа сделать свойство обязательным.

Способ 1: добавить поле required для каждого свойства.

Это синтаксис 3 версии схемы JSON:

array(
	'type'       => 'object',
	'properties' => array(
		'name'  => array(
			'type'     => 'string',
			'required' => true,
		),
		'color' => array(
			'type'     => 'string',
			'format'   => 'hex-color',
			'required' => true,
		),
	),
);

Способ 2: добавить поле required в общий массив где перечистить обязательные свойства.

Это синтаксис 4 версии схемы JSON:

register_post_meta( 'post', 'fixed_in', array(
	'type'         => 'object',
	'show_in_rest' => array(
		'single' => true,
		'schema' => array(
			'required'   => array( 'revision', 'version' ),
			'type'       => 'object',
			'properties' => array(
				'revision' => array(
					'type' => 'integer',
				),
				'version'  => array(
					'type' => 'string',
				),
			),
		),
	),
) );

Теперь следующий запрос не пройдет проверку:

{
	"title": "Check required properties",
	"content": "We should check that required properties are provided",
	"meta": {
		"fixed_in": {
			"revision": 47089
		}
	}
}

Если мета-поле fixed_in вообще не указать, то никакой ошибки не возникнет. Объект, определяющий список обязательных свойств, не определяет сам объект обязательным. Просто если объект указан, то обязательные свойства также должны быть указаны.

Синтаксис 4 версии не поддерживается для схем эндпоинта верхнего уровня в WP_REST_Controller::get_item_schema().

Если указана следующая схема, пользователь может отправить успешный запрос не указывая свойства title и content. Это происходит потому, что документ схемы сам по себе не используется для проверки, а вместо этого преобразуется в список определений параметров.

array(
	'$schema'    => 'http://json-schema.org/draft-04/schema#',
	'title'      => 'my-endpoint',
	'type'       => 'object',
	'required'   => array( 'title', 'content' ),
	'properties' => array(
		'title'   => array(
			'type' => 'string',
		),
		'content' => array(
			'type' => 'string',
		),
	),
);

меню

additionalProperties

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

По умолчанию схема JSON позволяет указывать свойства, которые не указаны в схеме.

Таким образом, чтобы следующее не прошло проверку, нужно указать параметр additionalProperties = false, т.е. неописанные в схеме (дополнительные) свойства запрещены.

array(
	'type'                 => 'object',
	'additionalProperties' => false,
	'properties'           => array(
		'name'  => array(
			'type' => 'string',
		),
		'color' => array(
			'type'   => 'string',
			'format' => 'hex-color',
		),
	),
);

Ключевое слово additionalProperties само может быть использовано как схема свойств объекта. Так неизвестные свойства должны будут пройти указанную проверку.

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

array(
	'type'                 => 'object',
	'properties'           => array(),
	'additionalProperties' => array(
		'type'       => 'object',
		'properties' => array(
			'name'  => array(
				'type'     => 'string',
				'required' => true,
			),
			'color' => array(
				'type'     => 'string',
				'format'   => 'hex-color',
				'required' => true,
			),
		),
	),
);

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

{
  "primary": {
	"name": "Primary",
	"color": "#ff6d69"
  },
  "secondary": {
	"name": "Secondary",
	"color": "#fecc50"
  }
}

А вот эти не пройдут:

{
  "primary": {
	"name": "Primary",
	"color": "#ff6d69"
  },
  "secondary": "#fecc50"
}

меню

patternProperties

Ключевое слово patternProperties аналогично ключевому слову additionalProperties, но позволяет утверждать, что свойство соответствует шаблону регулярных выражений. Ключевое слово - это объект, где каждое свойство является шаблоном регулярных выражений, а его значение - JSON схемой, используемой для проверки свойств, соответствующих этому шаблону.

Например, эта схема требует, чтобы каждое значение было шестнадцатеричным цветом, а свойство должно содержать только символы “слова”.

array(
  'type'                 => 'object',
  'patternProperties'    => array(
	'^\\w+$' => array(
	  'type'   => 'string',
	  'format' => 'hex-color',
	),
  ),
  'additionalProperties' => false,
);

В результате это пройдет проверку:

{
  "primary": "#ff6d69",
  "secondary": "#fecc50"
}

А это не пройдет:

{
  "primary": "blue",
  "$secondary": "#fecc50"
}

При проверке схемы patternProperties, если свойство не соответствует ни одному из шаблонов, это свойство будет разрешено и его содержимое не будет никак проверяться. Если такое поведение не подходит, то вам нужно запретить неизвестные (дополнительные) свойства с помощью параметра additionalProperties.

меню

minProperties / maxProperties

Используется для ограничения минимального и максимального количества свойств объекта (включительно). Это аналоги свойств minItems и maxItems у массива.

Это может быть полезно при описании схемы где разрешаются неизвестные свойства объекта, но их должно быть ограниченное кол-во. Например:

array(
  'type'                 => 'object',
  'additionalProperties' => array(
	'type'   => 'string',
	'format' => 'hex-color',
  ),
  'minProperties'        => 1,
  'maxProperties'        => 2,
);

Эти данные пройдут проверку:

{
  "primary": "#52accc",
  "secondary": "#096484"
}

А вот эти нет:

{
  "primary": "#52accc",
  "secondary": "#096484",
  "tertiary": "#07526c"
}
меню

enum

Позволяет указать список возможных значений передаваемого параметра (когда у параметра ограниченный список возможных значений).

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

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

array(
	'description' => __( 'Order sort attribute ascending or descending.' ),
	'type'        => 'string',
	'default'     => 'asc',
	'enum'        => array(
		'asc',
		'desc',
	),
);

Код из ядра, показывает как именно делается проверка:

if ( ! in_array( $value, $args['enum'], true ) ) {
	return new WP_Error( 'rest_invalid_param', sprintf( __( '%1$s is not one of %2$s.' ), $param, implode( ', ', $args['enum'] ) ) );
}
меню

oneOf / anyOf

Совпадение с одной или любой из описанных схем. Смотрите: rest_find_any_matching_schema(), rest_find_one_matching_schema().

Это расширенные ключевые слова, которые позволяют валидатору JSON схемы выбрать одну из многих схем для использования при проверке значения.

  • anyOf разрешает, чтобы значение соответствовало одной из указанных схем или нескольким схемам.
  • oneOf требует, чтобы значение подходило только под одну схему (не под две и более).

Например, эта схема позволяет отправлять массив "операций" в конечную точку. Каждая операция может быть либо "crop", либо "rotation".

array(
	'type'  => 'array',
	'items' => array(
		'oneOf' => array(
			array(
				'title'      => 'Crop',
				'type'       => 'object',
				'properties' => array(
					'operation' => array(
						'type' => 'string',
						'enum' => array(
							'crop',
						),
					),
					'x'         => array(
						'type' => 'integer',
					),
					'y'         => array(
						'type' => 'integer',
					),
				),
			),
			array(
				'title'      => 'Rotation',
				'type'       => 'object',
				'properties' => array(
					'operation' => array(
						'type' => 'string',
						'enum' => array(
							'rotate',
						),
					),
					'degrees'   => array(
						'type'    => 'integer',
						'minimum' => 0,
						'maximum' => 360,
					),
				),
			),
		),
	),
);

REST API пройдет циклом по каждой схеме, указанной в массиве oneOf и проверит соответствие. Если совпадает только одна схема, то проверка будет успешной. Если подходят несколько схем, проверка провалится. Если схемы не совпадают, то валидатор попытается найти наиболее близкую совпадающую схему и вернет соответствующее сообщение об ошибке.

operations[0] is not a valid Rotation. Reason: operations[0][degrees] must be between 0 (inclusive) and 360 (inclusive)

Чтобы генерировать понятные сообщения об ошибках, рекомендуется присвоить каждой схеме в массиве oneOf или anyOf свойство title.

меню