Skip to content

Commit

Permalink
Polish docs for Array, CAPTCHA, Cookie, Date, Directory and Download …
Browse files Browse the repository at this point in the history 
…helpers
  • Loading branch information
@narfbg
narfbg committed Nov 8, 2012
1 parent 0898e23 commit 48a8675
Show file tree
Hide file tree
Showing 5 changed files with 275 additions and 326 deletions.
66 changes: 27 additions & 39 deletions user_guide_src/source/helpers/array_helper.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,7 @@ arrays.
Loading this Helper
===================

This helper is loaded using the following code

::
This helper is loaded using the following code::

$this->load->helper('array');

Expand All @@ -21,20 +19,19 @@ The following functions are available:
element()
=========

.. php:method:: element($item, $array, $default = NULL)
:param string $item: Item to fetch from the array
:param array $array: Input array
:param boolean $default: What to return if the array isn't valid
:returns: NULL on failure or the array item.
.. php:function:: element($item, $array, $default = NULL)
:param string $item: Item to fetch from the array
:param array $array: Input array
:param bool $default: What to return if the array isn't valid
:returns: NULL on failure or the array item.

Lets you fetch an item from an array. The function tests whether the
array index is set and whether it has a value. If a value exists it is
returned. If a value does not exist it returns NULL, or whatever you've
specified as the default value via the third parameter. Example
specified as the default value via the third parameter.

::
Example::

$array = array(
'color' => 'red',
Expand All @@ -48,21 +45,19 @@ specified as the default value via the third parameter. Example
elements()
==========

.. php:function:: elements($items, $array, $default = NULL)
:param string $item: Item to fetch from the array
:param array $array: Input array
:param bool $default: What to return if the array isn't valid
:returns: NULL on failure or the array item.

Lets you fetch a number of items from an array. The function tests
whether each of the array indices is set. If an index does not exist it
is set to NULL, or whatever you've specified as the default value via
the third parameter.

.. php:method:: elements($items, $array, $default = NULL)
:param string $item: Item to fetch from the array
:param array $array: Input array
:param boolean $default: What to return if the array isn't valid
:returns: NULL on failure or the array item.

Example

::
Example::

$array = array(
'color' => 'red',
Expand All @@ -73,35 +68,30 @@ Example

$my_shape = elements(array('color', 'shape', 'height'), $array);

The above will return the following array

::
The above will return the following array::

array(
'color' => 'red',
'shape' => 'round',
'height' => NULL
);

You can set the third parameter to any default value you like

You can set the third parameter to any default value you like.
::

$my_shape = elements(array('color', 'shape', 'height'), $array, 'foobar');

The above will return the following array

::
The above will return the following array::

array(     
'color' => 'red',
'shape' => 'round',
'height' => 'foobar'
);

This is useful when sending the $_POST array to one of your Models.
This is useful when sending the ``$_POST`` array to one of your Models.
This prevents users from sending additional POST data to be entered into
your tables
your tables.

::

Expand All @@ -116,15 +106,14 @@ updated.
random_element()
================

Takes an array as input and returns a random element from it. Usage
example
.. php:function:: random_element($array)
.. php:method:: random_element($array)
:param array $array: Input array
:returns: string (a random element from the array)

:param array $array: Input array
:returns: String - Random element from the array.
Takes an array as input and returns a random element from it.

::
Usage example::

$quotes = array(
"I find that the harder I work, the more luck I seem to have. - Thomas Jefferson",
Expand All @@ -135,5 +124,4 @@ example
"Chance favors the prepared mind - Louis Pasteur"
);

echo random_element($quotes);

echo random_element($quotes);
99 changes: 43 additions & 56 deletions user_guide_src/source/helpers/captcha_helper.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,93 +11,85 @@ Loading this Helper
===================

This helper is loaded using the following code

::

$this->load->helper('captcha');

The following functions are available:

create_captcha($data)
=====================
create_captcha()
================

.. php:function:: function create_captcha($data = '', $img_path = '', $img_url = '', $font_path = '')
:param array $data: Array of data for the CAPTCHA
:param string $img_path: Path to create the image in
:param string $img_url: URL to the CAPTCHA image folder
:param string $font_path: Server path to font
:returns: array('word' => $word, 'time' => $now, 'image' => $img)

Takes an array of information to generate the CAPTCHA as input and
creates the image to your specifications, returning an array of
associative data about the image.

.. php:method:: function create_captcha($data = '', $img_path = '', $img_url = '', $font_path = '')
:param array $data: array of data for the CAPTCHA
:param string $img_path: path to create the image in
:param string $img_url: URL to the CAPTCHA image folder
:param string $font_path: server path to font
:returns: array('word' => $word, 'time' => $now, 'image' => $img)


::

[array] (
'image' => IMAGE TAG   
'time' => TIMESTAMP (in microtime)   
'word' => CAPTCHA WORD )
array(
'image' => IMAGE TAG
'time' => TIMESTAMP (in microtime)
'word' => CAPTCHA WORD
)

The "image" is the actual image tag:

::
The **image** is the actual image tag::

<img src="http://example.com/captcha/12345.jpg" width="140" height="50" />


The "time" is the micro timestamp used as the image name without the
The **time** is the micro timestamp used as the image name without the
file extension. It will be a number like this: 1139612155.3422

The "word" is the word that appears in the captcha image, which if not
The **word** is the word that appears in the captcha image, which if not
supplied to the function, will be a random string.

Using the CAPTCHA helper
------------------------

Once loaded you can generate a captcha like this

::
Once loaded you can generate a captcha like this::

$vals = array(     
'word' => 'Random word',     
'img_path' => './captcha/',     
'img_url' => 'http://example.com/captcha/',     
'font_path' => './path/to/fonts/texb.ttf',     
'img_width' => '150',     
'img_height' => 30,     
'expiration' => 7200     
$vals = array(
'word' => 'Random word',
'img_path' => './captcha/',
'img_url' => 'http://example.com/captcha/',
'font_path' => './path/to/fonts/texb.ttf',
'img_width' => '150',
'img_height' => 30,
'expiration' => 7200
);

$cap = create_captcha($vals); echo $cap['image'];

$cap = create_captcha($vals);
echo $cap['image'];

- The captcha function requires the GD image library.
- Only the img_path and img_url are required.
- If a "word" is not supplied, the function will generate a random
- Only the **img_path** and **img_url** are required.
- If a **word** is not supplied, the function will generate a random
ASCII string. You might put together your own word library that you
can draw randomly from.
- If you do not specify a path to a TRUE TYPE font, the native ugly GD
font will be used.
- The "captcha" folder must be writable (666, or 777)
- The "expiration" (in seconds) signifies how long an image will remain
- The **expiration** (in seconds) signifies how long an image will remain
in the captcha folder before it will be deleted. The default is two
hours.

Adding a Database
-----------------

In order for the captcha function to prevent someone from submitting,
you will need to add the information returned from create_captcha()
function to your database. Then, when the data from the form is
submitted by the user you will need to verify that the data exists in
the database and has not expired.
you will need to add the information returned from ``create_captcha()``
to your database. Then, when the data from the form is submitted by
the user you will need to verify that the data exists in the database
and has not expired.

Here is a table prototype

::
Here is a table prototype::

CREATE TABLE captcha (  
captcha_id bigint(13) unsigned NOT NULL auto_increment,  
Expand All @@ -109,9 +101,7 @@ Here is a table prototype
);

Here is an example of usage with a database. On the page where the
CAPTCHA will be shown you'll have something like this

::
CAPTCHA will be shown you'll have something like this::

$this->load->helper('captcha');
$vals = array(     
Expand All @@ -134,23 +124,20 @@ CAPTCHA will be shown you'll have something like this
echo '<input type="text" name="captcha" value="" />';

Then, on the page that accepts the submission you'll have something like
this

::
this::

// First, delete old captchas
$expiration = time() - 7200; // Two hour limit
$this->db->where('captcha_time < ', $expiration)
->delete('captcha');
->delete('captcha');

// Then see if a captcha exists:
$sql = "SELECT COUNT(*) AS count FROM captcha WHERE word = ? AND ip_address = ? AND captcha_time > ?";
$sql = 'SELECT COUNT(*) AS count FROM captcha WHERE word = ? AND ip_address = ? AND captcha_time > ?';
$binds = array($_POST['captcha'], $this->input->ip_address(), $expiration);
$query = $this->db->query($sql, $binds);
$row = $query->row();

if ($row->count == 0)
{     
echo "You must submit the word that appears in the image";
}

echo 'You must submit the word that appears in the image.';
}
Loading

0 comments on commit 48a8675

Please sign in to comment.