5 |
6 | # Datastar Package for Laravel
7 |
8 | ### A reactive hypermedia framework for Laravel.
9 |
10 | > [!WARNING]
11 | > **This package is in beta and its API may change.**
12 |
13 | This package integrates the [Datastar hypermedia framework](https://data-star.dev/) with [Laravel](https://laravel.com/), allowing you to create reactive frontends driven by Blade views _or_ controllers. It aims to replace the need for front-end frameworks such as React, Vue.js and Alpine.js + htmx, and instead lets you manage state and use logic from your Laravel backend.
14 |
15 | Use-cases:
16 |
17 | - Live search and filtering
18 | - Loading more elements / Infinite scroll
19 | - Paginating, ordering and filtering lists
20 | - Submitting forms and running actions
21 | - Pretty much anything to do with reactive front-ends
22 |
23 | ## License
24 |
25 | This package is licensed for free under the MIT License.
26 |
27 | ## Requirements
28 |
29 | This package requires [Laravel](https://laravel.com/) 11.0.0 or later.
30 |
31 | ## Installation
32 |
33 | Install manually using composer, then run the `artisan vendor:publish --tag=public` command to publish the public assets.
34 |
35 | ```shell
36 | composer require putyourlightson/laravel-datastar:^1.0.0-beta.1
37 |
38 | php artisan vendor:publish --tag=public
39 | ```
40 |
41 | ## Overview
42 |
43 | The Datastar package for Laravel allows you to handle backend requests by sending SSE events using [Blade directives](#blade-directives) in views _or_ [using controllers](#using-controllers). The former requires less setup and is more straightforward, while the latter provides more flexibility.
44 |
45 | Here’s a trivial example that toggles some backend state using the Blade view `datastar/toggle.blade.php` to handle the request.
46 |
47 | ```html
48 |
49 |
50 |
53 |
54 | ```
55 |
56 | ```php
57 | {{-- datastar/toggle.blade.php --}}
58 |
59 | @php
60 | $enabled = $signals->enabled;
61 | // Do something with the state and toggle the enabled state.
62 | $enabled = !$enabled;
63 | @endphp
64 |
65 | @mergesignals(['enabled' => $enabled])
66 |
67 | @mergefragments
68 |
69 | {{ $enabled ? 'Disable' : 'Enable' }}
70 |
71 | @endmergefragments
72 | ```
73 |
74 | ## Usage
75 |
76 | Start by reading the [Getting Started](https://data-star.dev/guide/getting_started) guide to learn how to use Datastar on the frontend. The Datastar package for Laravel only handles backend requests.
77 |
78 | > [!NOTE]
79 | > The Datastar [VSCode extension](https://marketplace.visualstudio.com/items?itemName=starfederation.datastar-vscode) and [IntelliJ plugin](https://plugins.jetbrains.com/plugin/26072-datastar-support) have autocomplete for all `data-*` attributes.
80 |
81 | When working with signals, note that you can convert a PHP array into a JSON object using the `json_encode` function.
82 |
83 | ```php
84 | @php
85 | $signals = ['foo' => 1, 'bar' => 2];
86 | @endphp
87 |
88 |
89 | ```
90 |
91 | ### Datastar Helper
92 |
93 | The `datastar()` helper function is available in Blade views and returns a `Datastar` helper that can be used to generate action requests to the Datastar controller. The Datastar controller renders a view containing one or [Blade directives](#blade-directives) that each send an SSE event. [Signals](#signals) are also sent as part of the request, and are made available in Datastar views using the `$signals` variable.
94 |
95 | #### `datastar()->get()`
96 |
97 | Returns a `@get()` action request to render a view at the given path. The value can be a file path _or_ a dot-separated path to a Blade view.
98 |
99 | ```php
100 | {{ datastar()->get('path.to.view') }}
101 | ```
102 |
103 | Variables can be passed into the view using a second argument. Any variables passed in will become available in the rendered view. Variables are tamper-proof yet visible in the source code in plain text, so you should avoid passing in any sensitive data.
104 |
105 | ```php
106 | {{ datastar()->get('path.to.view', ['offset' => 10]) }}
107 | ```
108 |
109 | #### `datastar()->post()`
110 |
111 | Works the same as [`datastar()->get()`](#datastar-get) but returns a `@post()` action request to render a view at the given path. A CSRF token is automatically generated and sent along with the request.
112 |
113 | ```php
114 | {{ datastar()->post('path.to.view') }}
115 | ```
116 |
117 | #### `datastar()->put()`
118 |
119 | Works the same as [`datastar()->post()`](#datastar-post) but returns a `@put()` action request.
120 |
121 | ```php
122 | {{ datastar()->put('path.to.view') }}
123 | ```
124 |
125 | #### `datastar()->patch()`
126 |
127 | Works the same as [`datastar()->post()`](#datastar-post) but returns a `@patch()` action request.
128 |
129 | ```php
130 | {{ datastar()->patch('path.to.view') }}
131 | ```
132 |
133 | #### `datastar()->delete()`
134 |
135 | Works the same as [`datastar()->post()`](#datastar-post) but returns a `@delete()` action request.
136 |
137 | ```php
138 | {{ datastar()->delete('path.to.view') }}
139 | ```
140 |
141 | #### `datastar()->getFragments()`
142 |
143 | Returns a `@get()` action request to render and automatically _merge_ the fragments contained in a view at the given path. The view should contain one or more fragments to be merged.
144 |
145 | ```php
146 | {{ datastar()->getFragments('path.to.view') }}
147 | ```
148 |
149 | ```html
150 |
The view should contain one or more fragments to be merged.
151 | ```
152 |
153 | ### Blade Directives
154 |
155 | #### `@mergefragments`
156 |
157 | Merges one or more fragments into the DOM.
158 |
159 | ```php
160 | @mergefragments
161 |
New fragment
162 | @endmergefragments
163 | ```
164 |
165 | #### `@removefragments`
166 |
167 | Removes one or more HTML fragments that match the provided selector from the DOM.
168 |
169 | ```php
170 | @removefragments('#old-fragment')
171 | ```
172 |
173 | #### `@mergesignals`
174 |
175 | Updates the signals with new values.
176 |
177 | ```php
178 | @mergesignals(['foo' => 1, 'bar' => 2])
179 | ```
180 |
181 | #### `@removesignals`
182 |
183 | Removes signals that match one or more provided paths.
184 |
185 | ```php
186 | @removesignals(['foo', 'bar'])
187 | ```
188 |
189 | #### `@executescript`
190 |
191 | Executes JavaScript in the browser.
192 |
193 | ```php
194 | @executescript
195 | alert('Hello, world!');
196 | @endexecutescript
197 | ```
198 |
199 | #### `@location`
200 |
201 | Redirects the browser by setting the location to the provided URI.
202 |
203 | ```php
204 | @location('/guide')
205 | ```
206 |
207 | ### Using Controllers
208 |
209 | You can send SSE events using your own controller _instead_ of the Datastar controller by using the `DatastarEventStream` trait. Return the `getStreamedResponse()` method, passing a callable into it that sends zero or more SSE events using methods provided.
210 |
211 | ```php
212 | // routes/web.php
213 |
214 | use App\Http\Controllers\MyController;
215 |
216 | Route::resource('/my-controller', MyController::class);
217 | ```
218 |
219 | ```php
220 | namespace App\Http\Controllers;
221 |
222 | use Illuminate\Routing\Controller;
223 | use Putyourlightson\Datastar\DatastarEventStream;
224 | use Symfony\Component\HttpFoundation\StreamedResponse;
225 |
226 | class MyController extends Controller
227 | {
228 | use DatastarEventStream;
229 |
230 | public function index(): StreamedResponse
231 | {
232 | return $this->getStreamedResponse(function() {
233 | $signals = $this->getSignals();
234 | $this->mergeSignals(['enabled' => $signals->enabled ? false : true]);
235 | $this->mergeFragments('
236 | ' . ($signals->enabled ? 'Enable' : 'Disable') . '
237 | ');
238 | });
239 | }
240 | }
241 | ```
242 |
243 | ### DatastarEventStream Trait
244 |
245 | #### `mergeFragments()`
246 |
247 | Merges one or more fragments into the DOM.
248 |
249 | ```php
250 | $this->mergeFragments('
New fragment
');
251 | ```
252 |
253 | #### `removeFragments()`
254 |
255 | Removes one or more HTML fragments that match the provided selector from the DOM.
256 |
257 | ```php
258 | $this->removeFragments('#old-fragment');
259 | ```
260 |
261 | #### `mergeSignals()`
262 |
263 | Updates the signals with new values.
264 |
265 | ```php
266 | $this->mergeSignals(['foo' => 1, 'bar' => 2]);
267 | ```
268 |
269 | #### `removeSignals()`
270 |
271 | Removes signals that match one or more provided paths.
272 |
273 | ```php
274 | $this->removeSignals(['foo', 'bar']);
275 | ```
276 |
277 | #### `executeScript()`
278 |
279 | Executes JavaScript in the browser.
280 |
281 | ```php
282 | $this->executeScript('alert("Hello, world!")');
283 | ```
284 |
285 | #### `location()`
286 |
287 | Redirects the browser by setting the location to the provided URI.
288 |
289 | ```php
290 | $this->location('/guide');
291 | ```
292 |
293 | #### `renderDatastarView()`
294 |
295 | Renders a Datastar view.
296 |
297 | ```php
298 | $this->renderDatastarView('datastar.toggle', ['enabled' => true]);
299 | ```
300 |
301 | ### Signals
302 |
303 | When working with signals, either in views rendered by the Datastar controller or by calling `$this->getSignals()`, you are working with a [Signals model](https://github.com/putyourlightson/laravel-datastar/blob/develop/src/Models/Signals.php), which provides a simple way to manage signals.
304 |
305 | ```php
306 | @php
307 | // Getting signal values.
308 | $username = $signals->username;
309 | $username = $signals->get('username');
310 | $username = $signals->get('user.username');
311 |
312 | // Setting signal values.
313 | $username = $signals->username('bobby');
314 | $username = $signals->set('username', 'bobby');
315 | $username = $signals->set('user.username', 'bobby');
316 | $username = $signals->setValues(['user.username' => 'bobby', 'success' => true]);
317 |
318 | // Removing signal values.
319 | $username = $signals->remove('username');
320 | $username = $signals->remove('user.username');
321 | @endphp
322 | ```
323 |
324 | > [!NOTE]
325 | > Signals updates _cannot_ be wrapped in `{% mergefragment %}` tags, since each update creates a server-sent event which will conflict with the fragment’s contents.
326 |
327 | ---
328 |
329 | Created by [PutYourLightsOn](https://putyourlightson.com/).
330 |
--------------------------------------------------------------------------------
/composer.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "putyourlightson/laravel-datastar",
3 | "description": "A reactive hypermedia framework for Laravel.",
4 | "version": "1.0.0-beta.8",
5 | "type": "library",
6 | "license": "mit",
7 | "require": {
8 | "php": "^8.2",
9 | "laravel/framework": "^11.0",
10 | "starfederation/datastar-php": "1.0.0-beta.17"
11 | },
12 | "require-dev": {
13 | "craftcms/ecs": "dev-main",
14 | "craftcms/phpstan": "dev-main",
15 | "pestphp/pest": "^3.0"
16 | },
17 | "autoload": {
18 | "psr-4": {
19 | "Putyourlightson\\Datastar\\": "src/"
20 | },
21 | "files": [
22 | "src/helpers.php"
23 | ]
24 | },
25 | "extra": {
26 | "laravel": {
27 | "providers": [
28 | "Putyourlightson\\Datastar\\DatastarServiceProvider"
29 | ]
30 | }
31 | },
32 | "scripts": {
33 | "check-cs": "ecs check --ansi",
34 | "fix-cs": "ecs check --ansi --fix",
35 | "phpstan": "phpstan --memory-limit=1G",
36 | "test": "vendor/bin/pest"
37 | },
38 | "config": {
39 | "allow-plugins": {
40 | "pestphp/pest-plugin": true
41 | },
42 | "optimize-autoloader": true,
43 | "sort-packages": true
44 | },
45 | "support": {
46 | "docs": "https://github.com/putyourlightson/laravel-datastar",
47 | "source": "https://github.com/putyourlightson/laravel-datastar",
48 | "issues": "https://github.com/putyourlightson/laravel-datastar/issues"
49 | }
50 | }
51 |
--------------------------------------------------------------------------------
/config/datastar.php:
--------------------------------------------------------------------------------
1 | true,
11 |
12 | /**
13 | * The name of the signals variable that will be injected into Datastar templates.
14 | */
15 | 'signalsVariableName' => 'signals',
16 |
17 | /**
18 | * The event options to override the Datastar defaults. Null values will be ignored.
19 | */
20 | 'defaultEventOptions' => [
21 | 'retryDuration' => 1000,
22 | ],
23 |
24 | /**
25 | * The fragment options to override the Datastar defaults. Null values will be ignored.
26 | */
27 | 'defaultFragmentOptions' => [
28 | 'settleDuration' => null,
29 | 'useViewTransition' => null,
30 | ],
31 |
32 | /**
33 | * The signal options to override the Datastar defaults. Null values will be ignored.
34 | */
35 | 'defaultSignalOptions' => [
36 | 'onlyIfMissing' => null,
37 | ],
38 |
39 | /**
40 | * The execute script options to override the Datastar defaults. Null values will be ignored.
41 | */
42 | 'defaultExecuteScriptOptions' => [
43 | 'autoRemove' => null,
44 | 'attributes' => null,
45 | ],
46 | ];
47 |
--------------------------------------------------------------------------------
/examples/hello-world/resources/views/datastar/hello-world.blade.php:
--------------------------------------------------------------------------------
1 | @php
2 | /** @var \Putyourlightson\Datastar\Models\Signals $signals */
3 | $delay = $signals->get('delay', 0);
4 | $message = 'Hello, world!';
5 | @endphp
6 |
7 | @for ($i = 0; $i < strlen($message); $i++)
8 | @mergefragments
9 |
14 |