diff --git a/.github/workflows/spellcheck.yml b/.github/workflows/spellcheck.yml index baa991604..4f62d4342 100644 --- a/.github/workflows/spellcheck.yml +++ b/.github/workflows/spellcheck.yml @@ -12,9 +12,9 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v4 - name: Set up Python - uses: actions/setup-python@v1 + uses: actions/setup-python@v5 with: python-version: 3.7 - name: Install dependencies diff --git a/.github/workflows/static.yml b/.github/workflows/static.yml index 5d9c92cdb..2410c53ba 100644 --- a/.github/workflows/static.yml +++ b/.github/workflows/static.yml @@ -15,7 +15,7 @@ jobs: steps: - name: Checkout code - uses: actions/checkout@v2 + uses: actions/checkout@v4 - name: Pull in optional dependencies run: composer require --no-update phpunit/phpunit toflar/psr6-symfony-http-cache-store:^3.0 @@ -33,7 +33,7 @@ jobs: steps: - name: Checkout code - uses: actions/checkout@v2 + uses: actions/checkout@v4 - name: Pull in optional dependencies run: composer require --no-update phpunit/phpunit toflar/psr6-symfony-http-cache-store:^3.0 @@ -49,7 +49,7 @@ jobs: steps: - name: Checkout code - uses: actions/checkout@v2 + uses: actions/checkout@v4 - name: PHP-CS-Fixer uses: docker://oskarstark/php-cs-fixer-ga diff --git a/doc/_static/custom.css b/doc/_static/custom.css new file mode 100644 index 000000000..34313878e --- /dev/null +++ b/doc/_static/custom.css @@ -0,0 +1,60 @@ +div.highlight { + background-color: #343131 !important; +} + +div.highlight pre { + border: none; + color: white !important; +} + +div.highlight pre span.n, +div.highlight pre span.na, +div.highlight pre span.nb, +div.highlight pre span.nc, +div.highlight pre span.nf, +div.highlight pre span.nx, +div.highlight pre span.kn { + color: white; +} + +div.highlight pre span.nv { + color: #6ab0de +} + +div.highlight pre span.k, +div.highlight pre span.o, +div.highlight pre span.nt +{ + color: #ff8400; +} + +div.highlight pre span.mi, +div.highlight pre span.s, +div.highlight pre span.s1, +div.highlight pre span.s2, +div.highlight pre span.sr, +div.highlight pre span.cp +{ + color: #56db3a; +} + +div.highlight pre span.hll { + background-color: #848484; +} + +div.highlight pre span.hll span.c1 { + color: #d8d8d8; +} + +div.highlight pre span.p { + color: #b3b3b3; +} + +table.highlighttable td { + padding: 0; +} + +table.highlighttable td div.linenodiv { + text-align: right; + width: 38px; +} diff --git a/doc/_static/tabs.css b/doc/_static/tabs.css deleted file mode 100644 index 7bd29689b..000000000 --- a/doc/_static/tabs.css +++ /dev/null @@ -1,103 +0,0 @@ -div.configuration-block { - position: relative; -} - -div.configuration-block ul.simple { - margin-left: 38px; -} - -div.configuration-block ul.simple li { - list-style: none; - float: left; - margin-left: 0; - margin-right: 1em; - padding: .2em .5em .5em .5em; - height: 38px; - background-color: #c9c9c9; -} - -div.configuration-block ul.simple li.selected { - background-color: #343131; - border-bottom: none; -} - -div.configuration-block ul.simple li.selected a { - color: white; -} - -div.highlight-varnish3, div.highlight-varnish4 { - border: none !important; -} - -div.configuration-block em { - font-style: normal; -} - -div.configuration-block div { - border-top: none; - position: absolute; - left: 0; - width: 100%; - max-width: 100%; - overflow: auto; -} - -div.configuration-block div div { - position: static; -} - -div.highlight { - background-color: #343131 !important; -} - -div.highlight pre { - border: none; - color: white !important; -} - -div.highlight pre span.n, -div.highlight pre span.na, -div.highlight pre span.nb, -div.highlight pre span.nc, -div.highlight pre span.nf, -div.highlight pre span.nx, -div.highlight pre span.kn { - color: white; -} - -div.highlight pre span.nv { - color: #6ab0de -} - -div.highlight pre span.k, div.highlight pre span.o { - color: #ff8400; -} - -div.highlight pre span.mi, -div.highlight pre span.s, -div.highlight pre span.s1, -div.highlight pre span.s2, -div.highlight pre span.sr { - color: #56db3a; -} - -div.highlight pre span.hll { - background-color: #848484; -} - -div.highlight pre span.hll span.c1 { - color: #d8d8d8; -} - -div.highlight pre span.p { - color: #b3b3b3; -} - -table.highlighttable td { - padding: 0; -} - -table.highlighttable td div.linenodiv { - text-align: right; - width: 38px; -} diff --git a/doc/_static/tabs.js b/doc/_static/tabs.js deleted file mode 100644 index 2852ee646..000000000 --- a/doc/_static/tabs.js +++ /dev/null @@ -1 +0,0 @@ -$(document).ready(function(){$("div.configuration-block [class^=highlight-]").hide();$("div.configuration-block").addClass("jsactive");$("div.configuration-block").addClass("clearfix");$("div.configuration-block").each(function(){var a=$("[class^=highlight-]:first",$(this));a.show();a.parents("ul:eq(0)").height(a.height()+40)});$("div.configuration-block li").each(function(){var a=$(":first",$(this)).html();$(":first ",$(this)).html("");$(":first ",$(this)).append(''+a+"");$(":first",$(this)).bind("click",function(){$("[class^=highlight-]",$(this).parents("ul")).hide();$("li",$(this).parents("ul")).removeClass("selected");$(this).parent().addClass("selected");var b=$("[class^=highlight-]",$(this).parent("li"));b.show();b.parents("ul:eq(0)").height(b.height()+40);return false})});$("div.configuration-block").each(function(){$("li:first",$(this)).addClass("selected")})}); diff --git a/doc/cache-invalidator.rst b/doc/cache-invalidator.rst index 081bfa441..5e696a91f 100644 --- a/doc/cache-invalidator.rst +++ b/doc/cache-invalidator.rst @@ -189,8 +189,7 @@ multiple times. If there are no requests to be sent, flush will simply do nothin Error handling -------------- -If an error occurs during ``flush()``, the method throws an -:source:`ExceptionCollection ` +If an error occurs during ``flush()``, the method throws an ``ExceptionCollection`` that contains an exception for each failed request to the proxy server. These exception are of two types: diff --git a/doc/conf.py b/doc/conf.py index 647d99f50..8946d6269 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -11,12 +11,6 @@ lexers['varnish3'] = CLexer() lexers['varnish4'] = CLexer() -on_rtd = os.environ.get('READTHEDOCS', None) == 'True' -if not on_rtd: # only import and set the theme if we're building docs locally - import sphinx_rtd_theme - html_theme = 'sphinx_rtd_theme' - html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] - primary_domain = 'php' highlight_language = 'php' @@ -29,10 +23,9 @@ # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = [ 'sphinx.ext.coverage', - 'sphinx.ext.extlinks', + 'sphinx_rtd_theme', + 'sphinx_tabs.tabs', 'sphinxcontrib.phpdomain', - 'sensio.sphinx.configurationblock', - 'sensio.sphinx.phpcode', 'sphinxcontrib.spelling' ] @@ -102,6 +95,8 @@ # -- Options for HTML output --------------------------------------------------- +html_theme = 'sphinx_rtd_theme' + # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. @@ -132,12 +127,8 @@ # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] -html_js_files = [ - 'tabs.js', -] - html_css_files = [ - 'tabs.css', + 'custom.css', 'fos.css', ] @@ -226,48 +217,7 @@ # If false, no module index is generated. #latex_domain_indices = True - -# -- Options for manual page output -------------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - ('index', 'foshttpcache', 'FOSHttpCache Documentation', - ['David Buchmann, David de Boer'], 1) -] - -# If true, show URL addresses after external links. -#man_show_urls = False - - -# -- Options for Texinfo output ------------------------------------------------ - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - ('index', 'FOSHttpCache', 'FOSHttpCache Documentation', - 'David Buchmann, David de Boer', 'FOSHttpCache', 'One line description of project.', - 'Miscellaneous'), -] - -# Documents to append as an appendix to all manuals. -#texinfo_appendices = [] - -# If false, no module index is generated. -#texinfo_domain_indices = True - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -#texinfo_show_urls = 'footnote' - rst_epilog = """ .. _FOSHttpCacheBundle: https://github.com/FriendsOfSymfony/FOSHttpCacheBundle .. _GitHub: https://github.com/FriendsOfSymfony/FOSHttpCache """ - -extlinks = {'source': ('https://github.com/FriendsOfSymfony/FOSHttpCache/blob/master/%s', '') } - -config_block = { - 'varnish3': 'Varnish 3', - 'varnish4': 'Varnish 4 - 6' -} diff --git a/doc/fastly-configuration.rst b/doc/fastly-configuration.rst index dc892ae1a..1e5213151 100755 --- a/doc/fastly-configuration.rst +++ b/doc/fastly-configuration.rst @@ -1,7 +1,7 @@ .. _fastly configuration: Fastly Configuration -------------------- +-------------------- Caching is enabled by default. All requests that are marked as cacheable will be cached. @@ -12,7 +12,7 @@ Caching is enabled by default. All requests that are marked as cacheable will be Tagging ~~~~~~~ -Fastly supports :term:`tagging` out of the box. +Fastly supports cache tagging out of the box. Configure the tag header to ``Surrogate-Keys``. (``fos_http_cache.tags.response_header`` if you use FOSHttpCacheBundle) Purge diff --git a/doc/nginx-configuration.rst b/doc/nginx-configuration.rst index ead7c8698..2e2b655be 100644 --- a/doc/nginx-configuration.rst +++ b/doc/nginx-configuration.rst @@ -24,7 +24,7 @@ NGINX does not support :term:`purge` functionality out of the box but you can ea `ngx_cache_purge `_ module. You just need to compile NGINX from sources adding ``ngx_cache_purge`` with ``--add-module``. -You can check the script :source:`install-nginx.sh ` to get an idea +You can check the script ``tests/install-nginx.sh`` to get an idea about the steps you need to perform. Then configure NGINX for purge requests: diff --git a/doc/proxy-clients.rst b/doc/proxy-clients.rst index 004d2c5b8..a602444f6 100644 --- a/doc/proxy-clients.rst +++ b/doc/proxy-clients.rst @@ -433,7 +433,7 @@ The recommended usage of the proxy client is to create an instance of Implementation Notes -------------------- -Each client is an implementation of :source:`ProxyClient `. +Each client is an implementation of ``ProxyClient``. All other interfaces, ``PurgeCapable``, ``RefreshCapable``, ``BanCapable``, ``TagCapable`` and ``ClearCapable`` extend this ``ProxyClient``. So each client implements at least one of the :ref:`invalidation methods ` depending on diff --git a/doc/requirements.txt b/doc/requirements.txt index d28a44649..fab75ae2e 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -1,8 +1,6 @@ -sphinx==1.8.5 -git+https://github.com/fabpot/sphinx-php.git -sphinx-rtd-theme==1.0.0 -sphinxcontrib-spelling +sphinx +sphinx-rtd-theme +sphinx-tabs sphinxcontrib-phpdomain +sphinxcontrib-spelling pyenchant -docutils==0.17.1 -jinja2<3.1.0 diff --git a/doc/response-tagging.rst b/doc/response-tagging.rst index 2f6a4f47e..3cf510fd4 100644 --- a/doc/response-tagging.rst +++ b/doc/response-tagging.rst @@ -74,7 +74,6 @@ up one header into multiple ones. This library ships with a ``MaxHeaderValueLengthFormatter`` that does the splitting for you. You give it an inner formatter and the maximum length like so:: - use FOS\HttpCache\TagHeaderFormatter\CommaSeparatedTagHeaderFormatter; use FOS\HttpCache\TagHeaderFormatter\MaxHeaderValueLengthFormatter diff --git a/doc/spelling_word_list.txt b/doc/spelling_word_list.txt index ddbffb280..19a43a2a0 100644 --- a/doc/spelling_word_list.txt +++ b/doc/spelling_word_list.txt @@ -5,6 +5,7 @@ cacheable config css Fastly +formatter getter getters hostname diff --git a/doc/testing-your-application.rst b/doc/testing-your-application.rst index c8ef3ebd5..3e449d3a6 100644 --- a/doc/testing-your-application.rst +++ b/doc/testing-your-application.rst @@ -48,7 +48,7 @@ use PHP’s built in web server. Include the WebServerListener in your .. literalinclude:: ../phpunit.xml.dist :prepend: - + :language: xml :start-after: @@ -80,7 +80,8 @@ Compare this library’s configuration to see how the constants are set: .. literalinclude:: ../phpunit.xml.dist :prepend: - + + :language: xml :start-after: @@ -332,4 +333,4 @@ correctly:: } For more ideas, see this library’s functional tests in the -:source:`tests/Functional/` directory. +``tests/Functional/`` directory. diff --git a/doc/user-context.rst b/doc/user-context.rst index a4d6f2eef..dd5d4b8e8 100644 --- a/doc/user-context.rst +++ b/doc/user-context.rst @@ -131,7 +131,7 @@ the current user context. Context Providers ~~~~~~~~~~~~~~~~~ -Each provider is passed the :source:`UserContext ` +Each provider is passed the ``UserContext`` and updates that with parameters which influence the varied response. A provider that looks at whether the user is authenticated could look like this:: diff --git a/doc/varnish-configuration.rst b/doc/varnish-configuration.rst index 22a46b4ce..f70a0997b 100644 --- a/doc/varnish-configuration.rst +++ b/doc/varnish-configuration.rst @@ -4,8 +4,8 @@ Varnish Configuration --------------------- Below you will find detailed Varnish configuration recommendations for the -features provided by this library. The configuration is provided for Varnish 3, -4 and 5. +features provided by this library. The configuration is provided for Varnish 4 and newer, +and - when it is different - for Varnish 3. Basic Varnish Configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -16,7 +16,7 @@ which IPs are allowed to issue invalidation requests. To use the provided configuration fragments, this ACL has to be named ``invalidators``. The most simple ACL, valid for Varnish version 3 or better, looks as follows: -.. code-block:: varnish3 +.. code-block:: C # /etc/varnish/your_varnish.vcl @@ -57,9 +57,9 @@ specified by the ``Vary`` header). Subroutines are provided in ``resources/config/varnish-[version]/fos_purge.vcl``. To enable this feature, add the following to ``your_varnish.vcl``: -.. configuration-block:: +.. tabs:: - .. code-block:: varnish4 + .. code-tab:: C Varnish 4-6 include "path-to-config/varnish/fos_purge.vcl"; @@ -67,7 +67,7 @@ To enable this feature, add the following to ``your_varnish.vcl``: call fos_purge_recv; } - .. code-block:: varnish3 + .. code-tab:: C Varnish 3 include "path-to-config/varnish-3/fos_purge.vcl"; @@ -98,9 +98,9 @@ its variants. Subroutines are provided in ``resources/config/varnish-[version]/fos_refresh.vcl``. To enable this feature, add the following to ``your_varnish.vcl``: -.. configuration-block:: +.. tabs:: - .. code-block:: varnish4 + .. code-tab:: C Varnish 4-6 include "path-to-config/varnish/fos_refresh.vcl"; @@ -108,7 +108,7 @@ To enable this feature, add the following to ``your_varnish.vcl``: call fos_refresh_recv; } - .. code-block:: varnish3 + .. code-tab:: C Varnish 3 include "path-to-config/varnish-3/fos_refresh.vcl"; @@ -127,9 +127,9 @@ Banning invalidates whole groups of cached entries with regular expressions. Subroutines are provided in ``resources/config/varnish-[version]/fos_ban.vcl`` To enable this feature, add the following to ``your_varnish.vcl``: -.. configuration-block:: +.. tabs:: - .. code-block:: varnish4 + .. code-tab:: C Varnish 4-6 include "path-to-config/varnish/fos_ban.vcl"; @@ -145,7 +145,7 @@ To enable this feature, add the following to ``your_varnish.vcl``: call fos_ban_deliver; } - .. code-block:: varnish3 + .. code-tab:: C Varnish 3 include "path-to-config/varnish-3/fos_ban.vcl"; @@ -209,7 +209,7 @@ To use ``xkey``, :ref:`configure the Varnish Client for xkey `, and include ``resources/config/varnish/fos_tags_xkey.vcl`` in your VCL: -.. code-block:: varnish4 +.. code-block:: C include "path-to-config/varnish/fos_tags_xkey.vcl"; @@ -237,17 +237,24 @@ invalidate in your :ref:`cache invalidator configuration httpDispatcher = $httpDispatcher; $this->options = $this->configureOptions()->resolve($options); diff --git a/src/SymfonyCache/CacheEvent.php b/src/SymfonyCache/CacheEvent.php index 7a9e02bed..21169d3ad 100644 --- a/src/SymfonyCache/CacheEvent.php +++ b/src/SymfonyCache/CacheEvent.php @@ -51,7 +51,7 @@ class CacheEvent extends BaseEvent * @param Response|null $response the response, if available * @param int $requestType the request type (default HttpKernelInterface::MASTER_REQUEST) */ - public function __construct(CacheInvalidation $kernel, Request $request, Response $response = null, $requestType = HttpKernelInterface::MASTER_REQUEST) + public function __construct(CacheInvalidation $kernel, Request $request, ?Response $response = null, $requestType = HttpKernelInterface::MASTER_REQUEST) { $this->kernel = $kernel; $this->request = $request; diff --git a/src/SymfonyCache/EventDispatchingHttpCache.php b/src/SymfonyCache/EventDispatchingHttpCache.php index adba06ebd..c531c4211 100644 --- a/src/SymfonyCache/EventDispatchingHttpCache.php +++ b/src/SymfonyCache/EventDispatchingHttpCache.php @@ -135,7 +135,7 @@ protected function invalidate(Request $request, $catch = false): Response * * @return Response|null The response to return, which might be provided/altered by a listener */ - protected function dispatch($name, Request $request, Response $response = null, $requestType = HttpKernelInterface::MASTER_REQUEST): ?Response + protected function dispatch($name, Request $request, ?Response $response = null, $requestType = HttpKernelInterface::MASTER_REQUEST): ?Response { if ($this->getEventDispatcher()->hasListeners($name)) { $event = new CacheEvent($this, $request, $response, $requestType); diff --git a/src/Test/EventDispatchingHttpCacheTestCase.php b/src/Test/EventDispatchingHttpCacheTestCase.php index d4a77aa60..898320cc4 100644 --- a/src/Test/EventDispatchingHttpCacheTestCase.php +++ b/src/Test/EventDispatchingHttpCacheTestCase.php @@ -43,7 +43,7 @@ abstract protected function getCacheClass(); * * @return CacheInvalidation|EventDispatchingHttpCache|MockObject */ - protected function getHttpCachePartialMock(array $mockedMethods = null) + protected function getHttpCachePartialMock(?array $mockedMethods = null) { $mock = $this ->getMockBuilder($this->getCacheClass()) diff --git a/tests/Functional/Fixtures/Symfony/AppCache.php b/tests/Functional/Fixtures/Symfony/AppCache.php index 59cc0e39e..3eda0579c 100644 --- a/tests/Functional/Fixtures/Symfony/AppCache.php +++ b/tests/Functional/Fixtures/Symfony/AppCache.php @@ -31,7 +31,7 @@ class AppCache extends HttpCache implements CacheInvalidation { use EventDispatchingHttpCache; - public function __construct(HttpKernelInterface $kernel, StoreInterface $store, SurrogateInterface $surrogate = null, array $options = []) + public function __construct(HttpKernelInterface $kernel, StoreInterface $store, ?SurrogateInterface $surrogate = null, array $options = []) { parent::__construct($kernel, $store, $surrogate, $options); diff --git a/tests/Unit/SymfonyCache/CleanupCacheTagsListenerTest.php b/tests/Unit/SymfonyCache/CleanupCacheTagsListenerTest.php index 08f6a10a4..d5106d451 100644 --- a/tests/Unit/SymfonyCache/CleanupCacheTagsListenerTest.php +++ b/tests/Unit/SymfonyCache/CleanupCacheTagsListenerTest.php @@ -59,7 +59,7 @@ public function testResponseHeaderIsCleanedUp() $this->assertFalse($response->headers->has('Foobar')); } - private function createEvent(Response $response = null) + private function createEvent(?Response $response = null) { return new CacheEvent( $this->createMock(CacheInvalidation::class),