Тут все привычно и понятно

• set($name, $value, $expiration = NULL)

  
  Устанавливает куку по имени $name в значение $value (на самом деле не совсем так, об этом позже). Параметр $expiration необязательный, он предназначен для указания срока актуальности куки. Например, если установить $expiration в 30, то получится время жизни 30 секунд от момента установки. Если параметр сделать равным нулю, то кука сохранится без времени жизни и удалится по окончании сессии браузера. Если же его вообще опустить, то будет взято значение по умолчанию – свойство Cookie::$expiration. Изначально оно равно нулю, но так как оно public, то его можно поменять под себя.
  Если установка куки прошла успешно, возвращается TRUE, иначе FALSE.

• get($key, $default = NULL)

  
  Возвращает куку по имени $key, а если не найдена – значение $default.

• delete($name)

  
  Удаляет куку $name. Происходит это следующим образом – текущее значение обнуляется, время жизни передается отрицательное (т.е. кука уже просрочена).

  Важно понимать, что при установке куки (классическим setcookie() или Cookie::set() – без разницы) новое значение будет установлено только после перезагрузки страницы (точнее после отправки HTTP-заголовков). Текущее же значение так и останется нетронутым в глобальном массиве $_COOKIE. Помните об этом, т.к. Cookie::set() изменяет только будущую куку, Cookie::get() пытается найти текущую, а Cookie::delete() удаляет как текущую, так и отправляемую.

Дополнительные параметры

В данном классе есть публичные статичные свойства, которые могут быть полезными при работе с куками. Одно из них (Cookie::$expiration) я уже упомянул, вот прочие:

• $path (‘/‘ по умолчанию). Используется для указания пути, для которого доступна кука. Например:
  

  Cookie::$path = '/'; // кука доступна для всего содержимого домена
  Cookie::$path = '/first/'; // кука видна только в папке first и ее содержимом

• $domain (NULL по умолчанию). Позволяет четко указать, для какого домена использовать куку. Например, для успешного использования кук поддоменами, надо указать имя родительского домена, предварив его точкой, например так:
  

  Cookie::$domain = '.first.com'; // кука будет доступна в доменах first.com, second.first.com и т.д.
  Cookie::$domain = 'second.first.com'; // куки будут недоступны для домена first.com!!

• $secure (FALSE по умолчанию). По названию понятно, что используется для безопасной отправки кук. Заголовки с куками будут отправлены только если используется протокол HTTPS.
• $httponly (FALSE по умолчанию). Это тоже опция безопасности. Если установить в TRUE, то доступ к кукам будет осуществляться только посредством HTTP-заголовков (т.е. отсекаются скриптовые языки, например JavaScript).

Изюминка

А зачем же тогда класс Cookie нужен, если он по сути не отличается от “родной” функции setcookie()? Так вот, данный класс позволяет дополнительно шифровать куки, а точнее – подписывать их. Дело в том, что метод Cookie::set() отправляет не переданное значение $value, а более сложную конструкцию, состоящую из двух частей – собственно значение и его подпись.

Вот, например, как выглядит у меня кука по имени ‘test1‘ и значением 1:
8f72531079624b276ca56e21b3162a648ba20431~1
Первая часть (до тильды) – это и есть таинственная подпись, потом идет нешифрованное значение – единица. В чем смысл? Разработчики постарались обезопасить куки от подмены значения. Когда мы передаем в Cookie::set() переменную, хэлпер формирует строковое значение из имени браузера ($_SERVER['HTTP_USER_AGENT']), имени куки и нового значения и генерирует хэш от полученной строки. В результате получается подпись для куки.
Обратите внимание, что само по себе значение ни от кого не прячется – оно доступно, просто откиньте тильду. Но вот если кто-то попробует подменить значение, то сгенерированная заново подпись не совпадет с переданной в куке – так система определит подмену и просто отбросит куку.

Все вышеуказанные действия по формировании подписи осуществляются в методе salt($name, $value). Помимо вышеперечисленных “ингредиентов”, перед хэшированием добавляется соль – значение параметра Cookie::$salt. Это, как и в модуле Auth, позволяет усложнить возможный подбор подписи куки, т.к. сам алгоритм известен. Просто поменяйте значение по умолчанию на какое-то свое, и никто не сможет изменить ваши подписанные куки.

С подписью кук могут возникнуть проблемы, если в вашем проекте предполагается установка кук посредством JavaScript. Конечно, можно портировать алгоритм формирования подписи из php, чтобы кука не отбрасывалась после установки, но тогда вам придется опубликовать и соль, что неприемлимо. Если все же очень хочется писать куки из скрипта, есть вариант немного переписать класс Cookie, чтобы он мог принимать и неподписанные куки (определять по отсутствию тильды в значении).

На этом все, класс небольшой и совсем не страшный

• Метод is_assoc(array $array). Позволяет проверить, является ли массив ассоциативным или нет. Алгоритм достаточно интересный (впервые увидел двойной вызов array_keys()). Стоит отметить, что если в исходном массиве ключи числовые, то все равно вернется TRUE (единственное исключение – массив с индексами от нуля с шагом 1, т.е. типичный неассоциативный массив).
• Метод path($array, $path, $default = NULL). Просто жизненно важный метод для работы с многомерными массивами, он позволяет обратиться в вложенному элементу, используя точку в качестве разделителей уровня вложенности. Например, если есть элемент

  $array['test']['var']['value']

  , то

  arr::path($array, 'test.var.value')

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

• Метод range($step = 10, $max = 100) вернет массив, заполненный элементами с шагом $step, вплоть до максимального числа $max. Не очень удобно, что нельзя указать начальный элемент (для данного метода он всегда будет совпадать с числом $step).
• Метод get($array, $key, $default = NULL), думаю, самый известный в данном классе. Он ищет элемент в массиве, с поддержкой дефолтного значения. Отличается от arr::path() тем, что ищет только в первом уровне вложенности.
• Метод extract($array, array $keys, $default = NULL). Метод, часто используемый для безопасной обработки данных глобальных массивов. Передавая массив $keys, мы определяем ключи, которые надо извлекать из массива $array. Все прочие ключи игнорируются. Если по какому-то ключу значение не найдено, подставляется $default. Например,

  $user_data = arr::extract($_POST, array('username', 'password', 'remember'), NULL)

  , позволит получить массив из ключей ‘username‘, ‘password‘ и ‘remember‘ массива $_POST.

• Метод binary_search($needle, $haystack, $sort = FALSE), в ветке 2.3.x использовавшийся для бинарного поиска, теперь просто вызывает array_search(), так что смысла в его использовании нет (оставлен для совместимости).
• Метод unshift(array & $array, $key, $val) позволяет вставить в начало ассоциативного массива значение $val по ключу $key.
• Метод map($callback, $array) рекурсивно применяет функцию $callback ко всем элементам $array, в том числе и подмассивам. В отличие от стандартного array_map(), arr::map() не работает с несколькими массивами (т.е.

  arr::map('trim', $array1, $array2, $array3)

  не пройдет).

• Метод merge(array $a1, array $a2) рекурсивно объединяет два массива. В отличие от array_merge_recursive(), она не принимает более 2х массивов. Кроме того, если массивы неассоциативные, то значения не будут дублироваться. Например,

  arr::merge(array('foo'), array('foo'))

  вернет

  array('foo')

  , а не

  array('foo', 'foo')

• Метод overwrite($array1, $array2) перезаписывает значения массива $array1 значениями из $array2. При этом новые ключи в $array1 не добавляются. Таким образом, пример из пункта про arr::extract() можно записать как

  arr::overwrite(array('username' => null, 'password' => null, 'remember' => null), $_POST);

• Метод callback($str) пытается разбить строковое представление вызова функции с параметрами на массив (функция, параметры). Например,

  arr::callback('foo::bar(1,2,$_POST)')

  вернет массив:
  

   array(2) 
  { 
     [0]=>  array(2) 
     { 
        [0]=>  string(3) "foo" 
        [1]=>  string(3) "bar" 
     } 
     [1]=>  array(3) 
     { 
        [0]=>  string(1) "1" 
        [1]=>  string(1) "2" 
        [2]=>  string(6) "$_POST"  
     } 
  }

  Если в строку заключать не в одиночные кавычки, а в двойные, то, что естественно, вместо строки $_POST подставится строковое представление этого глобального массива, т.е. строка ‘array‘.

  В версии 2.3.4 был похожий метод callback_string(), но он предусматривал использование квадратных скобок в строке, т.е. ‘foo::bar[1,2]‘. Вероятно это связано с использованием такого синтаксиса в Валидаторе, при объявлении правил.

• Метод flatten($array) преобразовывает многомерный массив в одномерный. Значения просто переносятся в “корень” массива. При этом ключи сохранятся только для конечных элементов (не являющихся массивами). Пример:
  

  $arr = array
  (
     '1' => array
     (
        '2' => 2, 
        '3' => array
        (
           4, 
           6 => 6
        )
     ), 
     '5' => 5
  );
  var_dump(arr::flatten($arr));

  
  В результате получим массив:
  

  array(4) 
  {
     [2]=>  int(2) 
     [0]=>  int(4)  
     [6]=>  int(6) 
     [5]=>  int(5) 
  }

  
  У элемента ‘4′ ключ сгенерирован заново, а массив под ключом ‘3′ исчез, оставив только свое содержимое. Тут стоит обратить внимание, что в целом ключи остались прежними. А что, если у двух элементов будет одно и то же значение ключа? Проверим:
  

  $arr = array
  (
     '1' => array
     (
        '2' => 2, 
        '3' => array
        (
           4, 
           5 => 6
        )
     ), 
     '5' => 5
  );
  var_dump(arr::flatten($arr));

  
  Здесь я для значения ‘6′ поменял ключ. В результате получим:
  array(3)
{
[2]=> int(2)
[0]=> int(4)
[5]=> int(5)
}
  Один элемент пропал – шестерка была затерта пятеркой, т.к. ключи совпадали. Так что будьте осторожнее с этим методом.

По сравнению с 2.3.4, в хэлпере не хватает таких методов, как rotate(), remove() и to_object(). Но их всегда можно перенести в третью ветку, ничего сложного в этом нет.

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

Постановка задачи

Изначально я использовал сессию, чтобы складировать туда переменные. Однако т.к. в различных контроллерах сохранялась разная информация, запоминать которую становилось все сложнее и сложнее, возникла необходимость в систематизации принципов хранения, обработки и получения данных. Толчком в нужном направлении для меня послужил хэлпер notice из дистрибутива YurikoCMS, о которой я недавно писал. Однако он не обеспечивал всего нужного мне функционала, а хотелось мне вот чего:

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

Нет ничего приятнее, чем решить проблему самостоятельно, поэтому я сел за написание скрипта.

Что вышло в итоге.

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

<?
// где-то в контроллере, идет валидация полей пользовательской формы
        if (!$this->user->validate($data, TRUE)) {
		message::add_validation($data->errors(), "auth");
		arr::remove('password', $_POST);
		arr::remove('password_confirm', $_POST);
		message::add($_POST, 'custom');
	}
        else {
		message::add(Kohana::lang('auth.registration_ok'), 'success');
		url::redirect(Router::uri('auth', array('method'=>'login')));
        }
 
// в шаблоне формы для ввода регистрационных данных
<ul>
...
  <li><!-- Email field  -->
    <?=message::render('validation', 'email')?>
    <label for="email"><?=Kohana::lang('auth.email')?></label>
    <input type="text" name="email" id="email" value="<?=message::custom('email')?>" />
  </li>
...
</ul>
 
// в шаблоне для большинства страниц
<div id="content">
	<?message::render()?>
	<?=$content?>
</div>

Метод message::add() является основным методом добавления информации в хэлпер. Так как ошибки валидации, возвращаемые методом errors(), являются массивом вида $fieldname=>$rulename, для них создан метод message::add_validation(), вторым параметром которого является имя i18n-файла, в котором описаны используемые формой ресурсы. Для показа сообщений используется метод message::render(), который может выводить как сообщения конкретного типа, так и все имеющиеся сообщения (за исключением ошибок валидации и custom-данных). Ошибки валидации показываются по отдельности перед полями ввода, с помощью все того же метода message::render(). А значения полей заполняются на основе работы метода message::custom(), который пытается найти в сообщениях типа ‘custom‘ указанную переменную. Дополнительно можно использовать метод get_type(), который вернет массив записей указанного типа без использования шаблонов (т.е. без вызова render()).
При использовании получаются примерно такие сообщения (кликабельно):

Форма регистрации с ошибками в отдельных полях

Сообщение о результате совершенных действий

Как это работает?

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

// в любом хуке
	Event::add('system.ready', array('message', 'init'));
	Event::add('system.send_headers', array('message', 'save'));
	Event::add('system.redirect', array('message', 'save'));

В момент инициализации считывается значение конфигурации из файла config/message.php, где должно быть прописано имя переменной для сохранения в сессии (параметр ‘message_key‘). В принципе, вы можете изменить текст хэлпера, просто я не хотел жестко прописывать какое-то конкретное значение.

Исходники

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

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

• limit_words($str, $limit = 100, $end_char = NULL). Обрезает строку $str до $limit слов. В конец результирующей строки добавляет символы $end_char (по умолчанию символ “многоточие”). Например, если вы не хотите в RSS или на главной показывать полный текст статьи, данная функция может стать полезной для проведения “обрезания”.
• limit_chars($str, $limit = 100, $end_char = NULL, $preserve_words = FALSE). Аналогична limit_words(), но в качестве единиц измерения длины строки выступают символы. Дополнительный параметр $preserve_words указывает, сохранять ли целыми слова (по умолчанию FALSE). Например:
  

  $str = 'Мама мыла раму';
  echo text::limit_words($str, 7); // выведет 'Мама мы...'
  echo text::limit_words($str, 7, "!"); // выведет 'Мама мы!'
  echo text::limit_words($str, 7, NULL, TRUE); // выведет 'Мама мыла...'

• alternate(). Позволяет чередовать строки, переданные в качестве параметров функции. Реализуется с помощью встроенного счетчика (статическая переменная), который увеличивается каждый раз, когда вызывается данная функция. Например, так можно чередовать светлые и темные строки в таблице:
  

  foreach($rows as $row) {
    echo '<tr class="', text::alternate("light", "dark"), '"><td>', $row->value, '</td></tr>';
  }

  А если надо обнулить счетчик, просто вызываем text::alternate() без параметров.

  К сожалению, функция не может принимать на входе массив строк, это было бы удобнее (ИМХО). Написал запрос разработчикам, может добавят такую возможность.

• random($type = ‘alnum’, $length = 8). Создает случайную строку указанного типа (параметр $type) и длины ($length). В качестве типа могут быть использованы: ‘alnum‘ (цифры и буквы латинского алфавита), ‘alpha‘ (буквы латинского алфавита), ‘hexdec‘ (цифры шестнадцатеричной системы счисления от 0 до f), ‘numeric‘ (цифры от 0 до 9), ‘nozero‘ (цифры от 1 до 9), ‘distinct‘ (цифры и числа, не имеющие схожих по начертанию аналогов, удобно для формирования текста т.н. капчи). Если строка $type не совпадает ни с одной из перечисленных, то она будет использована как список доступных символов (например, если вы захотите использовать не латинские символы, а кириллицу).
• reduce_slashes($str). Избавляет строку $str от повторяющихся слэшей. Работает только с прямым слэшем, т.е. с символом ‘/‘.
• censor($str, $badwords, $replacement = ‘#’, $replace_partial_words = FALSE). Функция-цензор, позволяет заменять в строке $str слова из “черного списка” $badwords на символы из параметра $replacement (по умолчанию символ “решетка”). Последний параметр $replace_partial_words указывает, заменять только целые слова, или любые вхождения данного шаблона. Для определения “целостности” слова используется псевдосимвол \b (описание).
  

  Будьте внимательны! Несмотря на название $replace_partial_words (“заменять части слов“), использование значения FALSE приводит к полной замене всех вхождений шаблона в тексте. Вы же не захотите видеть на вашем сайте строки “застра*** братуху, застра***”
  Update. Имя параметра оперативно исправили, в 2.4 все будет ОК.

  Например, сравните эти два вызова:
  

  $str = 'Маленький переполох';
  $bad =array('лох');
  echo text::censor($str, $bad, '*'); // выведет 'Маленький перепо***'
  echo text::censor($str, $bad, '*', TRUE); // выведет исходную строку

• similar(array $words). Находит общую подстроку, присутствующую во всех словах массива $words. Алгоритм прост: берется первое слово из массива и посимвольно проверяется совпадение во всех остальных элементах $words. Таким образом, similar(array(‘test’, ‘test!’)) вернет слово ‘test‘, а similar(‘test’, ‘1test’) вернет пустую строку.
• auto_link_urls($text). Как видно из названия, автоматически конвертирует в строке $text текстовые URL’ы в гиперссылки. Заменяет как ссылки с указанием протокола (http://, https://), так и без него (www.example.com). Уже оформленные ссылки не трогает. Для формирования тэгов использует html::anchor().
• auto_link_emails($text). Аналогична auto_link_urls(), но работает с почтовыми адресами (html::mailto()).
• auto_link($text). Два в одном: конвертирует и URL’ы, и email’ы. По сути просто последовательный вызов предыдущих двух функций.
• auto_p($str). Обрамляет абзацы текста тэгами

  . Двойные переводы каретки считаются за начало абзаца, одиночные заменяются на тэг
  . Многие html-тэги в тексте (типа TABLE, UL, DIV) в отдельные абзацы не выносятся. Удобна для автоматического форматирования текста, если вы не планируете использовать уже готовый текстовый редактор типа Tiny_MCE.

• bytes($bytes, $force_unit = NULL, $format = NULL, $si = TRUE). Преобразовывает $bytes (в байтах) в удобочитаемую строку с использованием более крупных единиц (Кб, Мб и т.д.). Параметр $force_unit определяет, в каких единицах вы хотели бы видеть результат (о допустимых единицах чуть ниже), если не указан – вычисляется автоматически. $format – аргумент, определяющий форматирование результата (синтаксис такой же, как в функции sprintf()), по умолчанию два знака после запятой, заполнение нулями. Последний параметр – выбор используемого стандарта, СИ (по умолчанию) или IEC.
  1. СИ. Доступны единицы: ‘B’, ‘kB’, ‘MB’, ‘GB’, ‘TB’, ‘PB’. 1 kB = 1000 B.
  2. IEC. Доступны единицы: ‘B’, ‘KiB’, ‘MiB’, ‘GiB’, ‘TiB’, ‘PiB’. 1KiB = 1024 B.

  Также, если вы указываете единицы вручную, выбор стандарта будет основываться на анализе этой единицы измерения (т.е. если вы хотите размер в ‘KiB‘, параметр $si можно не указывать).

  Будьте внимательны к подобным преобразованиям! Поскольку стандартная точность – два знака после запятой, 10 байт после явного преобразования в килобайты превратятся в ноль.

• widont($str). Предотвращает перенос строки перед последним словом в строке $str, заменяя пробел перед ним на символ “неразрывный пробел” ( ).

К чему я это все?

Самое интересное, что о функционале доброй половины хэлперов из дистрибутива фреймворка я и не подозревал, а ведь многие функции весьма полезны и актуальны. Меньше знаешь – лучше спишь?