README

English | Deutsch | Français

CloudCastle HttpRequest — современная PHP-библиотека для удобной, безопасной и расширяемой работы с HTTP-запросами, сессиями, cookie, файлами, заголовками, серверными переменными и окружением. Поддерживает автоматический разбор JSON и XML, паттерн Singleton, магические методы, глобальные вспомогательные функции и полностью покрыта тестами.

🧪 Статистика тестов и покрытия

• PHPUnit: 163 теста, 194 утверждения, 2 пропущено
• Покрытие строк: 90.43% (624 / 690)
• Покрытие методов: 73.33% (44 / 60)
• Покрытие классов: 61.54% (8 / 13)
• Последний запуск: 2025-06-29
• Среднее время выполнения тестов: ~0.5 сек

📎 Быстрые ссылки

• Документация
• Примеры
• Архитектура
• FAQ
• Changelog
• Issues
• Pull Requests

⚙️ Требования

• PHP >= 8.3
• Расширения: ext-json, ext-mbstring
• Совместимость: любой фреймворк, поддержка PSR-4

🚀 CI/CD Workflow (GitHub Actions)

name: CI

on:
  push:
    branches: [ main, master ]
  pull_request:
    branches: [ main, master ]

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        php-version: [ '8.3', '8.4' ]
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: ${{ matrix.php-version }}
          extensions: mbstring, xml, simplexml, curl, json, session
          coverage: xdebug

      - name: Install dependencies
        run: composer install --no-interaction

      - name: Run tests
        run: composer test

      - name: Run static analysis
        run: composer phpstan

      - name: Coverage (text)
        run: composer coverage

      - name: Coverage (HTML)
        run: composer coverage-html

      - name: Generate documentation
        run: composer docs-gen

      - name: Upload coverage report
        uses: actions/upload-artifact@v4
        with:
          name: coverage-report
          path: coverage-report/

      - name: Upload documentation
        uses: actions/upload-artifact@v4
        with:
          name: documentation
          path: build/api/ 

🗺️ Архитектура (Mermaid)

graph TD;
  Request -->|has| Cookie
  Request -->|has| Session
  Request -->|has| Headers
  Request -->|has| Get
  Request -->|has| Post
  Request -->|has| Files
  Request -->|has| Server
  Request -->|has| Env
  Cookie -->|uses| GetInstanceTrait
  Session -->|uses| SetExpireTrait
  Headers -->|uses| GetDataTrait
  Headers -->|uses| GetInstanceTrait
  Env -->|uses| GetDataTrait
  Env -->|uses| GetInstanceTrait

📋 Содержание

• Возможности
• Установка
• Быстрый старт
• Архитектура и компоненты
• Подробное API
• Примеры использования
• Вспомогательные функции
• Интеграция с фреймворками
• Тестирование
• FAQ
• Лицензия и контакты

🚀 Возможности

• Универсальный доступ к данным запроса: GET, POST, COOKIE, SESSION, FILES, HEADERS, SERVER, ENV
• Автоматический разбор JSON и XML тела запроса
• Удобная работа с cookie и сессиями (Singleton, цепочки вызовов, сериализация)
• Безопасная работа с загруженными файлами
• Глобальные функции для быстрого доступа к данным
• Гибкая настройка времени жизни сессий и cookie
• Совместимость с современными стандартами PHP (8.1+)
• Полное покрытие тестами (PHPUnit)
• Расширяемость и интеграция с любыми фреймворками

📦 Установка

Через Composer (рекомендуется)

composer require cloud-castle/http-request

Ручная установка

git clone https://github.com/zorinalexey/cloud-castle-http-request
cd http-request
composer install

⚡ Быстрый старт

<?php
require_once 'vendor/autoload.php';

use CloudCastle\HttpRequest\Request;

// Получить singleton Request
$request = Request::getInstance();

// Получить параметры запроса
$userId = $request->get('user_id');
$session = $request->session;
$all = $request->all();

// Получить POST/GET/COOKIE/FILES/HEADERS
$post = $request->post;
$get = $request->get;
$cookie = $request->cookie;
$files = $request->files;
$headers = $request->headers;

🏗️ Архитектура и компоненты

• Request — основной фасад для доступа ко всем данным запроса.
• Get/Post — доступ к GET/POST данным.
• Cookie — управление cookie (установка, получение, удаление, очистка).
• Session — управление сессиями.
• Files/UploadFile — работа с загруженными файлами.
• Headers — работа с HTTP-заголовками.
• Server/Env — доступ к серверным переменным и окружению.
• Вспомогательные функции: request(), cookies(), session(), files(), headers(), get(), post(), env().

📚 Подробное API

Request

Cookie

Session

Files/UploadFile

Headers

Server/Env

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

Глобальная функция request()

// Получить параметр из любого источника (GET, POST, ...), либо объект Request
$id = request('id');
$name = request('name', 'default_name');
$request = request();

// Получить все данные запроса
$all = request()->all();

// Работа с файлами
$avatar = request()->files('avatar');
if ($avatar && $avatar->isUploaded()) {
    $avatar->save('/uploads/avatars/');
}

// Работа с cookie
request()->cookie->set('token', 'abc123');
$token = request()->cookie->get('token');

// Работа с сессией
request()->session->set('user_id', 42);
$userId = request()->session->get('user_id');

Работа с заголовками

$headers = request()->headers;
$userAgent = $headers->get('User-Agent');
$headers->X_Custom_Header = 'custom_value';

Работа с JSON и XML

// Если Content-Type: application/json
$data = request()->all(); // автоматически преобразуется в массив

// Если Content-Type: application/xml
$data = request()->all(); // автоматически преобразуется в массив

Работа с GET/POST

$get = request()->get;
$post = request()->post;

$name = $get->get('name');
$email = $post->get('email');

Работа с серверными переменными и окружением

$server = request()->server;
$env = request()->env;

$host = $server->get('HTTP_HOST');
$phpVersion = $env->get('PHP_VERSION');

Работа с UploadFile

$file = request()->files('avatar');
if ($file && $file->isUploaded()) {
    $file->save('/uploads/avatars/');
    echo $file->getOriginalName();
    echo $file->getSize();
    echo $file->getMimeType();
}

🛠️ Вспомогательные функции

• request($key = null, $default = null) — универсальный доступ к данным запроса
• cookies($key = null, $default = null) — доступ к cookie
• session($key = null, $default = null) — доступ к сессии
• files($key = null) — доступ к загруженным файлам
• headers($key = null, $default = null) — доступ к заголовкам
• get($key = null, $default = null) — доступ к GET
• post($key = null, $default = null) — доступ к POST
• env($key = null, $default = null) — доступ к переменным окружения

🌐 Интеграция с фреймворками

Laravel

use CloudCastle\HttpRequest\Request;
$request = Request::getInstance();
$userId = $request->get('user_id');

Symfony

use CloudCastle\HttpRequest\Request;
$request = Request::getInstance();
$headers = $request->headers;

Slim

use CloudCastle\HttpRequest\Request;
$app->post('/api', function ($req, $res, $args) {
    $request = Request::getInstance();
    $data = $request->all();
    // ...
});

🧪 Тестирование

composer install
vendor/bin/phpunit --testdox

❓ FAQ и Troubleshooting

• Q: Почему не видны новые переменные окружения?
  A: Используйте $env->get('VAR') после установки, убедитесь, что переменная есть в $_ENV.
• Q: Как добавить поддержку нового Content-Type?
  A: Добавьте его в массив Request::$contentTypes.
• Q: Как протестировать загрузку файлов?
  A: Используйте мок-объекты и подмену $_FILES в тестах.
• Q: Как сбросить singleton?
  A: Используйте метод resetInstance() для нужного класса.

🚦 Performance & Security

• Используйте HTTPS для работы с cookie и сессиями.
• Не храните чувствительные данные в cookie.
• Для production отключайте подробные ошибки.
• Используйте статический анализ и покрытие тестами для повышения качества.

🤝 Contributing

• Форкните репозиторий, создайте ветку, отправьте PR.
• Соблюдайте PSR-12, пишите тесты для новых фич.
• Все изменения должны проходить CI/CD.
• Для багов — создавайте issue с подробным описанием.

📝 Changelog

Смотрите CHANGELOG.md для истории изменений.

📬 Контакты и поддержка

• Email: zorinalexey59292@gmail.com
• Telegram: @CloudCastle85
• Issues: https://github.com/zorinalexey/Http-Request/issues

📄 Лицензия

MIT License. См. файл LICENSE.

📝 Лицензия и контакты

MIT © Алексей Зорин (zorinalexey59292@gmail.com)

• GitHub проекта
• Вопросы и предложения

CloudCastle HttpRequest — ваш универсальный инструмент для работы с HTTP в PHP!