PHPackages                             pavloniym/nginx-cache - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Caching](/categories/caching)
4. /
5. pavloniym/nginx-cache

ActiveLibrary[Caching](/categories/caching)

pavloniym/nginx-cache
=====================

nginx cache package for routes

v1.0.1(6mo ago)058MITPHPPHP ^8.0

Since Feb 16Pushed 6mo agoCompare

[ Source](https://github.com/pavloniym/nginx-cache)[ Packagist](https://packagist.org/packages/pavloniym/nginx-cache)[ RSS](/packages/pavloniym-nginx-cache/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (2)Dependencies (2)Versions (3)Used By (0)

Laravel Nginx Cache
===================

[](#laravel-nginx-cache)

Laravel-пакет для автоматической генерации конфигурационных файлов кеширования Nginx на основе атрибутов в контроллерах.

Оглавление
----------

[](#оглавление)

1. [Зачем это нужно](#%D0%B7%D0%B0%D1%87%D0%B5%D0%BC-%D1%8D%D1%82%D0%BE-%D0%BD%D1%83%D0%B6%D0%BD%D0%BE)
2. [Установка](#%D1%83%D1%81%D1%82%D0%B0%D0%BD%D0%BE%D0%B2%D0%BA%D0%B0)
3. [Настройка Nginx](#%D0%BD%D0%B0%D1%81%D1%82%D1%80%D0%BE%D0%B9%D0%BA%D0%B0-nginx)
4. [Использование](#%D0%B8%D1%81%D0%BF%D0%BE%D0%BB%D1%8C%D0%B7%D0%BE%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5)
5. [Типы кеша](#%D1%82%D0%B8%D0%BF%D1%8B-%D0%BA%D0%B5%D1%88%D0%B0)
6. [Команды](#%D0%BA%D0%BE%D0%BC%D0%B0%D0%BD%D0%B4%D1%8B)
7. [Тестирование](#%D1%82%D0%B5%D1%81%D1%82%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5)
8. [Кастомные типы кеша](#%D0%BA%D0%B0%D1%81%D1%82%D0%BE%D0%BC%D0%BD%D1%8B%D0%B5-%D1%82%D0%B8%D0%BF%D1%8B-%D0%BA%D0%B5%D1%88%D0%B0)
9. [Интеграция в CI/CD](#%D0%B8%D0%BD%D1%82%D0%B5%D0%B3%D1%80%D0%B0%D1%86%D0%B8%D1%8F-%D0%B2-cicd)

---

Зачем это нужно
---------------

[](#зачем-это-нужно)

Вместо ручного прописывания `location` блоков для кеширования API-ендпоинтов в конфигах Nginx, пакет сканирует контроллеры и генерирует конфиг автоматически. Вы используете атрибут `#[NginxCache]` на методе контроллера, а пакет берет на себя формирование корректных правил для Nginx.

Установка
---------

[](#установка)

```
composer require pavloniym/nginx-cache
```

Опубликуйте конфигурационный файл:

```
php artisan vendor:publish --tag=config
```

В файле `config/nginx-cache.php` укажите путь, куда PHP должен записывать файл для Nginx:

```
return [
    'path' => '/etc/nginx/conf.d/_cache',      // Директория для конфигов
    'filename' => 'locations.conf',             // Имя выходного файла
];
```

---

Настройка Nginx
---------------

[](#настройка-nginx)

Для работы кеширования необходимо подготовить инфраструктуру на стороне Nginx.

### Глобальные настройки (`nginx.conf`)

[](#глобальные-настройки-nginxconf)

Добавьте настройки зоны кеша и GeoIP в блок `http`:

```
http {

    # ...

    # Add GeoIP2 (for SimpleWithCountryIsoCache)
    geoip2 /var/www/html/storage/app/geoip/geoip.mmdb {
        auto_reload 5m;
        $geoip2_metadata_country_build metadata build_epoch;
        $geoip2_data_country_code default=NL source=$http_x_forwarded_for country iso_code;
        $geoip2_data_country_name country names en;
    }

    # ...

    # Cache options
    proxy_cache_path /var/cache/nginx levels=2 keys_zone=httpCache:1024M inactive=12h max_size=4096M;
    proxy_cache_lock on;
    proxy_cache_methods GET HEAD POST;
    proxy_cache_min_uses 1;
    proxy_ignore_headers Expires Cache-Control;
    proxy_cache_use_stale error timeout invalid_header http_500 http_502 http_503 http_504;
    proxy_cache_revalidate on;
    proxy_cache_background_update on;
}
```

### Настройка виртуального хоста

[](#настройка-виртуального-хоста)

Подключите сгенерированный файл внутри блока `server`:

```
server {
    # ...

    set $backend http://127.0.0.1:8080;
    proxy_cache httpCache;

    # Add cache locations config
    include /etc/nginx/conf.d/_cache/locations.conf;

    location / {
        try_files $uri $uri/ @backend;
    }

    location @backend {
        internal;
        proxy_pass $backend$suffix;
    }

    # ...
}
```

---

Использование
-------------

[](#использование)

Просто добавьте атрибут к методу вашего контроллера:

```
use Pavloniym\NginxCache\Attributes\NginxCache;
use Pavloniym\NginxCache\Types\SimpleCache;

class ProductController extends Controller
{
    #[NginxCache(type: SimpleCache::class, duration: 300)]
    public function index()
    {
        return Product::all();
    }
}
```

---

Типы кеша
---------

[](#типы-кеша)

- **SimpleCache**: Базовый кеш по URI и телу запроса.
- **SimpleWithCountryIsoCache**: Кеш, разделенный по странам (требует GeoIP2).
- **SimpleWithIpCache**: Персонализированный кеш по IP адресу.
- **UserCache**: Кеш для авторизованных пользователей (учитывает сессии и Bearer токены).
- **WithoutCache**: Явное отключение кеширования для метода.

---

Команды
-------

[](#команды)

**Просмотр списка всех кешируемых роутов:**

```
php artisan nginx-cache:list
```

**Генерация файла конфигурации:**

```
php artisan nginx-cache:build
```

---

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

[](#тестирование)

Пакет покрыт автотестами на `PHPUnit` + `Orchestra Testbench`.

Установка dev-зависимостей:

```
composer install
```

Запуск всех тестов:

```
composer test
```

---

Кастомные типы кеша
-------------------

[](#кастомные-типы-кеша)

Вы можете создавать свои правила, наследуя класс `NginxCacheType`:

```
namespace App\NginxCache;

use Pavloniym\NginxCache\Contracts\Types\NginxCacheType;

class HeavyCache extends NginxCacheType
{
    public string $key = '$request_uri';
    public string $duration = '3600s';
    public string $responses = '200';
}
```

---

Интеграция в CI/CD
------------------

[](#интеграция-в-cicd)

Для автоматизации обновления правил добавьте выполнение команды в процесс деплоя:

```
php artisan nginx-cache:build
nginx -s reload
```

Требования
----------

[](#требования)

- PHP 8.1+
- Laravel 9.x / 10.x / 11.x / 12.x
- Nginx с модулем `ngx_http_geoip2_module` (для соответствующих типов кеша)

License
-------

[](#license)

MIT

---

**Важно:** Пакет только генерирует конфиги. Настройку базовых параметров Nginx (proxy\_cache\_path, upstream и т.д.) делай вручную в основном конфиге.

###  Health Score

34

—

LowBetter than 74% of packages

Maintenance69

Regular maintenance activity

Popularity11

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity41

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

2

Last Release

181d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/60f2554666408e1fdb9afac6f2ad657382a942e4e9998fd90ee4f27cd32ee90f?d=identicon)[pavloniym](/maintainers/pavloniym)

---

Top Contributors

[![pavloniym](https://avatars.githubusercontent.com/u/17234942?v=4)](https://github.com/pavloniym "pavloniym (9 commits)")

---

Tags

cachelaravelnginxnginx-cache

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/pavloniym-nginx-cache/health.svg)

```
[![Health](https://phpackages.com/badges/pavloniym-nginx-cache/health.svg)](https://phpackages.com/packages/pavloniym-nginx-cache)
```

###  Alternatives

[iazaran/smart-cache

Smart Cache is a caching optimization package designed to enhance the way your Laravel application handles data caching. It intelligently manages large data sets by compressing, chunking, or applying other optimization strategies to keep your application performant and efficient.

21114.2k](/packages/iazaran-smart-cache)[phpfastcache/phpssdb

PHP SSDB Driver for phpFastCache

14736.9k1](/packages/phpfastcache-phpssdb)[rapidwebltd/rw-file-cache

RW File Cache is a PHP File-based Caching Library. Its syntax is designed to closely resemble the PHP memcache extension.

15196.8k7](/packages/rapidwebltd-rw-file-cache)[yuzuru-s/redis-recommend

Wrapping Redis's sorted set APIs for specializing recommending operations.

392.9k](/packages/yuzuru-s-redis-recommend)[ichhabrecht/intcache

Turn uncachable page objects into cacheable links

193.9k](/packages/ichhabrecht-intcache)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)