/**
 * @package     Joomla.Platform
 * @subpackage  HTTP
 *
 * @copyright   Copyright (C) 2005 - 2013 Open Source Matters, Inc. All rights reserved.
 * @license     GNU General Public License version 2 or later; see LICENSE
 */

defined('JPATH_PLATFORM') or die();

jimport('joomla.environment.uri');

/**
 * HTTP client class.
 *
 * @package     Joomla.Platform
 * @subpackage  HTTP
 * @since       11.3
 */
class JHttp
{
    /**
     * @var    JRegistry  Options for the HTTP client.
                             Параметры для HTTP клиента.
     * @since  11.3
     */
    protected $options;

    /**
     * @var    JHttpTransport  The HTTP transport object to use in sending HTTP requests.
                                HTTP транспорт объект для использования в отправке запросов HTTP.
     * @since  11.3
     */
    protected $transport;

    /**
     * Constructor.
     *
     * @param   JRegistry       &$options   Client options object.
                                             Объект Параметры клиента.
     * @param   JHttpTransport  $transport  The HTTP transport object.
                                                 объект HTTP транспорт.
     *
     * @since   11.3
     */
    public function __construct(JRegistry &$options = null, JHttpTransport $transport = null)
    {
        $this->options   = isset($options) ? $options : new JRegistry;
        $this->transport = isset($transport) ? $transport : new JHttpTransportStream($this->options);
    }

    /**
     * Get an option from the HTTP client.  
        Получить парометр из HTTP клиента.
     *
     * @param   string  $key  The name of the option to get.
                                 Имя параметра для того чтобы получить.
     *
     * @return  mixed  The option value.
                         Значение параметра.
     *
     * @since   11.3
     */
    public function getOption($key)
    {
        return $this->options->get($key);
    }

    /**
     * Set an option for the HTTP client.
     *     Задать параметр для HTTP клиента.
     
     * @param   string  $key    The name of the option to set.
                                 Имя параметра для задания.
     * @param   mixed   $value  The option value to set.
                                     Задаваемое значение параметра.
     *
     * @return  JHttp  This object for method chaining.
                         Объект This для объединения методов в цепочку.
     *
     * @since   11.3
     */
    public function setOption($key, $value)
    {
        $this->options->set($key, $value);

        return $this;
    }

    /**
     * Method to send the OPTIONS command to the server.
      Метод для отправки команды OPTIONS(Параметры) на сервер.
     *
     * @param   string  $url      Path to the resource.
                                     Путь к ресурсу.
     * @param   array   $headers  An array of name-value pairs to include in the header of the request.
                                     Массив  пар имя - значение для включения в заголовок запроса.
     *
     * @return  JHttpResponse
     *
     * @since   11.3
     */
    public function options($url, array $headers = null)
    {
        return $this->transport->request('OPTIONS', new JUri($url), null, $headers);
    }

    /**
     * Method to send the HEAD command to the server.
      Метод для отправки команды HEAD на сервер.
     *
     * @param   string  $url      Path to the resource.
                                     Путь к ресурсу.
     * @param   array   $headers  An array of name-value pairs to include in the header of the request.
                                    Массив  пар имя - значение для включения в заголовок запроса.
     *
     * @return  JHttpResponse
     *
     * @since   11.3
     */
    public function head($url, array $headers = null)
    {
        return $this->transport->request('HEAD', new JUri($url), null, $headers);
    }

    /**
     * Method to send the GET command to the server.
         Метод для отправки команды GET сервер.
     *
     * @param   string  $url      Path to the resource.
                                     Путь к ресурсу.
     * @param   array   $headers  An array of name-value pairs to include in the header of the request.
                                     Массив  пар имя - значение для включения в заголовок запроса.
     *
     * @return  JHttpResponse
     *
     * @since   11.3
     */
    public function get($url, array $headers = null)
    {
        return $this->transport->request('GET', new JUri($url), null, $headers);
    }

    /**
     * Method to send the POST command to the server.
      Метод для отправки команды POST на сервер.
     *
     * @param   string  $url      Path to the resource.
                                     Путь к ресурсу.
     * @param   mixed   $data     Either an associative array or a string to be sent with the request.
                                     Ассоциативный массив или строка, отправляемая с запросом.
     * @param   array   $headers  An array of name-value pairs to include in the header of the request.
                                      Массив  пар имя - значение для включения в заголовок запроса.
     *
     * @return  JHttpResponse
     *
     * @since   11.3
     */
    public function post($url, $data, array $headers = null)
    {
        return $this->transport->request('POST', new JUri($url), $data, $headers);
    }

    /**
     * Method to send the PUT command to the server.
        Метод для отправки команды PUT(ПОЛОЖИТЬ) на сервер.
     *
     * @param   string  $url      Path to the resource.
                                     Путь к ресурсу.
     * @param   mixed   $data     Either an associative array or a string to be sent with the request.
                                      Ассоциативный массив или строка, отправляемая с запросом.
     * @param   array   $headers  An array of name-value pairs to include in the header of the request.
                                       Массив  пар имя - значение для включения в заголовок запроса.
     *
     * @return  JHttpResponse
     *
     * @since   11.3
     */
    public function put($url, $data, array $headers = null)
    {
        return $this->transport->request('PUT', new JUri($url), $data, $headers);
    }

    /**
     * Method to send the DELETE command to the server.
      Метод для отправки команды DELETE(УДАЛИТЬ) на сервер.
     *
     * @param   string  $url      Path to the resource.
                                     Путь к ресурсу.
     * @param   array   $headers  An array of name-value pairs to include in the header of the request.
                                       Массив  пар имя - значение для включения в заголовок запроса.
     *
     * @return  JHttpResponse
     *
     * @since   11.3
     */
    public function delete($url, array $headers = null)
    {
        return $this->transport->request('DELETE', new JUri($url), null, $headers);
    }

    /**
     * Method to send the TRACE command to the server.
      Метод для отправки команды TRACE(СЛЕД) на сервер.
     *
     * @param   string  $url      Path to the resource.
                                     Путь к ресурсу.
     * @param   array   $headers  An array of name-value pairs to include in the header of the request.
                                       Массив  пар имя - значение для включения в заголовок запроса.
     *
     * @return  JHttpResponse
     *
     * @since   11.3
     */
    public function trace($url, array $headers = null)
    {
        return $this->transport->request('TRACE', new JUri($url), null, $headers);
    }
}