Skip to content

Commit 3c6d62a

Browse files
darkweakdarkweak
authored
feat(documentation): check all documentations to be up to date (#570)
* feat(documentation): check all documentations to be up to date * fix(website): better CSS code blocks, try to remove baseurl to have a dynamic CSS loading
1 parent 749cc80 commit 3c6d62a

File tree

3 files changed

+259
-5
lines changed

3 files changed

+259
-5
lines changed

‎docs/website/assets/docs/scss/style.scss‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -98,11 +98,13 @@ h4 {
9898
padding-top: 0.75em;
9999
}
100100

101-
div.code-toolbar {
101+
div.code-toolbar, .docs-content .main-content pre {
102102
border-radius: 1rem;
103-
& > pre {
104-
border-radius: 1rem !important;
105-
}
103+
}
104+
105+
code[class*="language-"], pre[class*="language-"], .code-toolbar, .docs-content .main-content pre, code[class*="language-"]::-webkit-scrollbar, pre[class*="language-"]::-webkit-scrollbar {
106+
background: var(--inline-code-bg) !important;
107+
color: var(--body-color) !important;
106108
}
107109

108110
.top-header {

‎docs/website/content/docs/uses-cases/api-platform.md‎

Lines changed: 252 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,252 @@
1+
+++
2+
weight = 602
3+
title = "HTTP caching with API Platform"
4+
icon = "deployed_code"
5+
description = "🚀🕷️ Blazing fast API Platform"
6+
tags = ["Beginners"]
7+
+++
8+
9+
## What is API Platform
10+
API Platform is a next-generation web framework designed to easily create API-first projects without compromising extensibility and flexibility.
11+
12+
## Minimalistic setup
13+
14+
### Caddyfile
15+
By default API Platform uses FrankenPHP (that is built on top of the Caddy webserver) as reverse-proxy. So we can edit the provided Caddyfile `api/frankenphp/Caddyfile` and configure our caddy instance with these minimal changes:
16+
```diff
17+
{
18+
{$CADDY_GLOBAL_OPTIONS}
19+
20+
frankenphp {
21+
{$FRANKENPHP_CONFIG}
22+
}
23+
+
24+
+ cache {
25+
+ api {
26+
+ souin
27+
+ }
28+
+ cdn {
29+
+ strategy hard
30+
+ }
31+
+ key {
32+
+ headers Authorization
33+
+ }
34+
+ otter
35+
+ }
36+
}
37+
{$CADDY_EXTRA_CONFIG}
38+
39+
{$SERVER_NAME:localhost} {
40+
log {
41+
# Redact the authorization query parameter that can be set by Mercure
42+
format filter {
43+
request>uri query {
44+
replace authorization REDACTED
45+
}
46+
}
47+
}
48+
49+
+ cache
50+
+
51+
root * /app/public
52+
encode zstd br gzip
53+
54+
mercure {
55+
# Transport to use (default to Bolt)
56+
transport_url {$MERCURE_TRANSPORT_URL:bolt:///data/mercure.db}
57+
# Publisher JWT key
58+
publisher_jwt {env.MERCURE_PUBLISHER_JWT_KEY} {env.MERCURE_PUBLISHER_JWT_ALG}
59+
# Subscriber JWT key
60+
subscriber_jwt {env.MERCURE_SUBSCRIBER_JWT_KEY} {env.MERCURE_SUBSCRIBER_JWT_ALG}
61+
# Allow anonymous subscribers (double-check that it's what you want)
62+
anonymous
63+
# Enable the subscription API (double-check that it's what you want)
64+
subscriptions
65+
# Extra directives
66+
{$MERCURE_EXTRA_DIRECTIVES}
67+
}
68+
69+
vulcain
70+
71+
# Add links to the API docs and to the Mercure Hub if not set explicitly (e.g. the PWA)
72+
header ?Link `</docs.jsonld>; rel="http://www.w3.org/ns/hydra/core#apiDocumentation", </.well-known/mercure>; rel="mercure"`
73+
# Disable Topics tracking if not enabled explicitly: https://github.com/jkarlin/topics
74+
header ?Permissions-Policy "browsing-topics=()"
75+
76+
# Matches requests for HTML documents, for static files and for Next.js files,
77+
# except for known API paths and paths with extensions handled by API Platform
78+
@pwa expression `(
79+
header({'Accept': '*text/html*'})
80+
&& !path(
81+
'/docs*', '/graphql*', '/bundles*', '/contexts*', '/_profiler*', '/_wdt*',
82+
'*.json*', '*.html', '*.csv', '*.yml', '*.yaml', '*.xml'
83+
)
84+
)
85+
|| path('/favicon.ico', '/manifest.json', '/robots.txt', '/sitemap*', '/_next*', '/__next*')
86+
|| query({'_rsc': '*'})`
87+
88+
# Comment the following line if you don't want Next.js to catch requests for HTML documents.
89+
# In this case, they will be handled by the PHP app.
90+
reverse_proxy @pwa http://{$PWA_UPSTREAM}
91+
92+
php_server
93+
}
94+
```
95+
96+
### Dockerfile
97+
You now have to update the Dockerfile `api/Dockerfile` to build the FrankenPHP/Caddy instance with Souin (or the cache-handler):
98+
```diff
99+
#syntax=docker/dockerfile:1
100+
101+
# Adapted from https://github.com/dunglas/symfony-docker
102+
103+
104+
# Versions
105+
- FROM dunglas/frankenphp:1-php8.3 AS frankenphp_upstream
106+
+ FROM dunglas/frankenphp:latest-builder AS builder
107+
+ COPY --from=caddy:builder /usr/bin/xcaddy /usr/bin/xcaddy
108+
+
109+
+ ENV CGO_ENABLED=1 XCADDY_SETCAP=1 XCADDY_GO_BUILD_FLAGS="-ldflags \"-w -s -extldflags '-Wl,-z,stack-size=0x80000'\""
110+
+ RUN xcaddy build \
111+
+ --output /usr/local/bin/frankenphp \
112+
+ --with github.com/dunglas/frankenphp \
113+
+ --with github.com/dunglas/frankenphp/caddy \
114+
+ --with github.com/dunglas/mercure/caddy \
115+
+ --with github.com/dunglas/vulcain/caddy \
116+
+ --with github.com/dunglas/caddy-cbrotli \
117+
+ # Use this one in production
118+
+ # --with github.com/caddyserver/cache-handler \
119+
+ --with github.com/darkweak/souin/plugins/caddy \
120+
+ --with github.com/darkweak/storages/otter/caddy
121+
+
122+
+ FROM dunglas/frankenphp:latest AS frankenphp_upstream
123+
+ COPY --from=builder --link /usr/local/bin/frankenphp /usr/local/bin/frankenphp
124+
125+
126+
# The different stages of this Dockerfile are meant to be built into separate images
127+
# https://docs.docker.com/develop/develop-images/multistage-build/#stop-at-a-specific-build-stage
128+
# https://docs.docker.com/compose/compose-file/#target
129+
130+
131+
# Base FrankenPHP image
132+
FROM frankenphp_upstream AS frankenphp_base
133+
134+
WORKDIR /app
135+
136+
# persistent / runtime deps
137+
# hadolint ignore=DL3008
138+
RUN apt-get update && apt-get install --no-install-recommends -y \
139+
acl \
140+
file \
141+
gettext \
142+
git \
143+
&& rm -rf /var/lib/apt/lists/*
144+
145+
# https://getcomposer.org/doc/03-cli.md#composer-allow-superuser
146+
ENV COMPOSER_ALLOW_SUPERUSER=1
147+
148+
RUN set -eux; \
149+
install-php-extensions \
150+
@composer \
151+
apcu \
152+
intl \
153+
opcache \
154+
zip \
155+
;
156+
157+
###> recipes ###
158+
###> doctrine/doctrine-bundle ###
159+
RUN set -eux; \
160+
install-php-extensions pdo_pgsql
161+
###< doctrine/doctrine-bundle ###
162+
###< recipes ###
163+
164+
COPY --link frankenphp/conf.d/app.ini $PHP_INI_DIR/conf.d/
165+
COPY --link --chmod=755 frankenphp/docker-entrypoint.sh /usr/local/bin/docker-entrypoint
166+
COPY --link frankenphp/Caddyfile /etc/caddy/Caddyfile
167+
168+
ENTRYPOINT ["docker-entrypoint"]
169+
170+
HEALTHCHECK --start-period=60s CMD curl -f http://localhost:2019/metrics || exit 1
171+
CMD [ "frankenphp", "run", "--config", "/etc/caddy/Caddyfile" ]
172+
173+
# Dev FrankenPHP image
174+
FROM frankenphp_base AS frankenphp_dev
175+
176+
ENV APP_ENV=dev XDEBUG_MODE=off
177+
VOLUME /app/var/
178+
179+
RUN mv "$PHP_INI_DIR/php.ini-development" "$PHP_INI_DIR/php.ini"
180+
181+
RUN set -eux; \
182+
install-php-extensions \
183+
xdebug \
184+
;
185+
186+
COPY --link frankenphp/conf.d/app.dev.ini $PHP_INI_DIR/conf.d/
187+
188+
CMD [ "frankenphp", "run", "--config", "/etc/caddy/Caddyfile", "--watch" ]
189+
190+
# Prod FrankenPHP image
191+
FROM frankenphp_base AS frankenphp_prod
192+
193+
ENV APP_ENV=prod
194+
ENV FRANKENPHP_CONFIG="import worker.Caddyfile"
195+
196+
RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini"
197+
198+
COPY --link frankenphp/conf.d/app.prod.ini $PHP_INI_DIR/conf.d/
199+
COPY --link frankenphp/worker.Caddyfile /etc/caddy/worker.Caddyfile
200+
201+
# prevent the reinstallation of vendors at every changes in the source code
202+
COPY --link composer.* symfony.* ./
203+
RUN set -eux; \
204+
composer install --no-cache --prefer-dist --no-dev --no-autoloader --no-scripts --no-progress
205+
206+
# copy sources
207+
COPY --link . ./
208+
RUN rm -Rf frankenphp/
209+
210+
RUN set -eux; \
211+
mkdir -p var/cache var/log; \
212+
composer dump-autoload --classmap-authoritative --no-dev; \
213+
composer dump-env prod; \
214+
composer run-script --no-dev post-install-cmd; \
215+
chmod +x bin/console; sync;
216+
217+
```
218+
219+
And voilà, your API Platform project has now an HTTP cache in front of your application. But you would probably enable the automatic invalidation to be sure your responses are always up to date, especially to refresh the list of your entity when you create a new item or update one that is in this list.
220+
221+
To do that, you have to update the `api/config/packages/api_platform.yml` file to enable the HTP cache invalidation:
222+
```diff
223+
api_platform:
224+
title: Hello API Platform
225+
version: 1.0.0
226+
# Mercure integration, remove if unwanted
227+
mercure:
228+
include_type: true
229+
formats:
230+
jsonld: ['application/ld+json']
231+
docs_formats:
232+
jsonld: ['application/ld+json']
233+
jsonopenapi: ['application/vnd.openapi+json']
234+
html: ['text/html']
235+
# Good defaults for REST APIs
236+
defaults:
237+
stateless: true
238+
cache_headers:
239+
vary: ['Content-Type', 'Authorization', 'Origin']
240+
extra_properties:
241+
standard_put: true
242+
rfc_7807_compliant_errors: true
243+
# change this to true if you use controllers
244+
use_symfony_listeners: false
245+
246+
+ http_cache:
247+
+ invalidation:
248+
+ urls: [ 'http://php/souin-api/souin' ]
249+
+ purger: api_platform.http_cache.purger.souin
250+
```
251+
252+
You're now ready to handle tons of requests that will be served by the HTTP cache.

‎docs/website/hugo.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
baseURL = 'https://docs.souin.io/'
1+
# baseURL = 'https://docs.souin.io/'
22
languageCode = 'en-us'
33
title = "Souin's documentation"
44

0 commit comments

Comments
 (0)