Merge pull request #19 from tonysm/new-http-turbo-stream-response-api

New Turbo Stream HTTP Response API

Author: tonysm

.github/workflows/php-cs-fixer.yml

@@ -15,7 +15,7 @@ jobs:
       - name: Run PHP CS Fixer
         uses: docker://oskarstark/php-cs-fixer-ga
         with:
-          args: --config=.php_cs.dist --allow-risky=yes
+          args: --config=.php-cs-fixer.dist.php --allow-risky=yes
 
       - name: Commit changes
         uses: stefanzweifel/git-auto-commit-action@v4

.gitignore

@@ -1,6 +1,7 @@
 .idea
 .php_cs
 .php_cs.cache
+.php-cs-fixer.cache
 .phpunit.result.cache
 build
 composer.lock

.php-cs-fixer.dist.php

@@ -0,0 +1,45 @@
+<?php
+
+$finder = Symfony\Component\Finder\Finder::create()
+    ->notPath('bootstrap/*')
+    ->notPath('storage/*')
+    ->notPath('resources/view/mail/*')
+    ->in([
+        __DIR__ . '/src',
+        __DIR__ . '/tests',
+    ])
+    ->name('*.php')
+    ->notName('*.blade.php')
+    ->ignoreDotFiles(true)
+    ->ignoreVCS(true);
+
+$config = new PhpCsFixer\Config();
+
+$config->setRules([
+    '@PSR2' => true,
+    'array_syntax' => ['syntax' => 'short'],
+    'ordered_imports' => ['sort_algorithm' => 'alpha'],
+    'no_unused_imports' => true,
+    'not_operator_with_successor_space' => true,
+    'trailing_comma_in_multiline' => true,
+    'phpdoc_scalar' => true,
+    'unary_operator_spaces' => true,
+    'binary_operator_spaces' => true,
+    'blank_line_before_statement' => [
+        'statements' => ['break', 'continue', 'declare', 'return', 'throw', 'try'],
+    ],
+    'phpdoc_single_line_var_spacing' => true,
+    'phpdoc_var_without_name' => true,
+    'class_attributes_separation' => [
+        'elements' => [
+            'method' => 'one',
+        ],
+    ],
+    'method_argument_space' => [
+        'on_multiline' => 'ensure_fully_multiline',
+        'keep_multiple_spaces_after_comma' => true,
+    ],
+    'single_trait_insert_per_statement' => true,
+])->setFinder($finder);
+
+return $config;

.php_cs.dist

@@ -1,4 +1,4 @@
-<p align="center"><img src="/art/turbo-laravel-logo.svg" alt="Logo Turbo Laravel" /></p>
+<p align="center" style="margin-top: 2rem; margin-bottom: 2rem;"><img src="/art/turbo-laravel-logo.svg" alt="Logo Turbo Laravel" /></p>
 
 <p align="center">
     <a href="https://github.com/tonysm/turbo-laravel/workflows/Tests/badge.svg">
@@ -203,9 +203,7 @@ Route::post('posts/{post}/comments', function (Post $post) {
     $comment = $post->comments()->create(/** params */);
 
     if (request()->wantsTurboStream()) {
-        return response()->turboStreamView('comments.turbo.created_stream', [
-            'comment' => $comment,
-        ]);
+        return response()->turboStream()->append($comment);
     }
 
     return back();
@@ -214,7 +212,7 @@ Route::post('posts/{post}/comments', function (Post $post) {
 
 The `request()->wantsTurboStream()` macro added to the request will check if the request accepts Turbo Stream and return `true` or `false` accordingly.
 
-Here's what that `comments.turbo.created_stream.blade.php` view could look like:
+Here's what the HTML response will look like:
 
 ```blade
 <turbo-stream action="append" target="comments">
@@ -224,87 +222,94 @@ Here's what that `comments.turbo.created_stream.blade.php` view could look like:
 </turbo-stream>
 ```
 
+Most of these things were "guessed" based on the [naming conventions](#conventions) we talked about earlier. But you can override most things, like so:
+
+```php
+return response()->turboStream($comment)->target('post_comments');
+```
+
+The model is optional, as it's only used to figure out the defaults based on the model state. You could manually create that same response like so:
+
+```php
+return response()->turboStream()
+    ->target('comments')
+    ->action('append')
+    ->view('comments._comment', ['comment' => $comment]);
+```
+
 There are 5 _actions_ in Turbo Streams. They are:
 
 * `append` & `prepend`: to add the elements in the target element after the existing contents or before, respectively
 * `replace`: will replace the existing element entirely with the contents of the `template` tag in the Turbo Stream
 * `update`: will keep the target and only replace the contents of it with the contents of the `template` tag in the Turbo Stream
-* `remove`: will remove the element. This one doesn't need a `<template>` tag.
+* `remove`: will remove the element. This one doesn't need a `<template>` tag. It accepts either an instance of a Model or the DOM ID of the element to be removed as a string.
+
+Which means you will find shorthand methods for them all, like:
+
+```php
+response()->turboStream()->append($comment);
+response()->turboStream()->prepend($comment);
+response()->turboStream()->replace($comment);
+response()->turboStream()->update($comment);
+response()->turboStream()->remove($comment);
+```
 
 You can read more about Turbo Streams in the [Turbo Handbook](https://turbo.hotwire.dev/handbook/streams).
 
-If you notice, all we're doing in the `comments.turbo.created_stream.blade.php` view is wrapping the comment's partial with a Turbo Stream tag. You can alternatically delegate the generation of the Turbo Stream tag to a `response()->turboStream()` macro, which will essentially do the same thing, but in this case you wouldn't need that `comments.turbo.created_stream.blade.php` anymore:
+These shorthand methods return a pending object for the response which you can chain and override everything you want on it:
 
 ```php
-Route::post('posts/{post}/comments', function (Post $post) {
-    $comment = $post->comments()->create(/** params */);
+return response()->turboStream()
+    ->append($comment)
+    ->view('comments._comment_card', ['comment' => $comment]);
+```
 
-    if (request()->wantsTurboStream()) {
-        return response()->turboStream($comment);
-    }
+As mentioned earlier, passing a model to the `response()->turboStream()` macro will pre-fill the pending response object with some defaults based on the model's state.
 
-    return back();
-});
-```
+It will build a `remove` Turbo Stream if the model was deleted (or if it is trashed - in case it's a Soft Deleted model), an `append` if the model was recently created (which you can override the action as the second parameter of the macro), a `replace` if the model was just updated (you can also override the action as the second parameter.) Here's how overriding would look like:
 
-Again, this will detect that your model was recently created and generate an `append` Turbo Stream to a `comments` target (using the plural name of your model's basename for that) and render the model's partial inside a `template` tag, similarly to what we were doing manually.
+```php
+return response()->turboStream($comment, 'append');
+```
 
-The `response()->turboStream()` macro will generate a _replace_ Turbo Stream action targeting your model's DOM ID when you are only updating the model. In the same way, if you have deleted the model, it will generate a _remove_ Turbo Stream also using the model's DOM ID as target.
+<a name="custom-turbo-stream-views"></a>
+### Custom Turbo Stream Views
 
-If you're not using the model partial convention, you may stick with the `response()->turboStreamView()` version instead and specify your own Turbo Stream views. See the [conventions section](#ceventions) to read more about this.
+If you're not using the model partial [convention](#conventions) or if you have some more complex Turbo Stream constructs, you may use the `response()->turboStreamView()` version instead and specify your own Turbo Stream views.
 
-You may override the partial name by implementing a `hotwirePartialName` method in your model. You may also have more control over the data that is passed down to the partial by implementing the `hotwirePartialData` method, like so:
+This is what it looks like:
 
 ```php
-class Comment extends Model
-{
-  public function hotwirePartialName()
-  {
-    return 'my.non.conventional.partial.name';
-  }
-
-  public function hotwirePartialData()
-  {
-    return [
-      'lorem' => false,
-      'ipsum' => true,
-      'comment' => $this,
-    ];
-  }
-}
+return response()->turboStreamView('comments.turbo.created_stream', [
+    'comment' => $comment,
+]);
 ```
 
-You may also override the resource name used as target in the case wher you're generating a Turbo Stream for recently created models, as well as the DOM ID that will be used as targets when your model was either updated or deleted by implementing the following methods:
+And here's an example of a more complex custom Turbo Stream view:
 
-```php
-class Comment extends Model
-{
-  public function hotwireTargetResourcesName()
-  {
-    return 'admin_comments';
-  }
+```blade
+@include('layouts.turbo.flash_stream')
 
-  public function hotwireTargetDomId()
-  {
-    return "admin_comment_{$this->id}";
-  }
-}
+<turbo-stream target="comments" action="append">
+    <template>
+        @include('comments._comment', ['comment' => $comment])
+    </template>
+</turbo-stream>
 ```
 
-<a name="custom-turbo-stream-views"></a>
-### Custom Turbo Stream Views
-
-Erlier I showed you a custom Turbo Stream view before I showed you how to auto-generate Turbo Stream views for you models. The name and location of that view was no accident. When auto-generating the Turbo Stream views for your model using the `response()->turboStream()` helper function, it will first check if you have a Custom Turbo Stream View in place for this model and, if so, it will use that view instead of generating one from scratch.
-
-This way, you can have more control over your Turbo Stream responses. To use custom Turbo Stream views, you may create a `turbo` folder in the model's resource views folder and name them after the model event you want to override, like so:
+Remember, these are Blade views, so you have the full power of Blade at your hands. In this example, we're including a shared Turbo Stream partial which could append any flash messages we may have. That `layouts.turbo.flash_stream` could look like this:
 
-| Model Event | Expected View |
-|---|---|
-| `created` | `{resource}/turbo/created_stream.blade.php` |
-| `updated` | `{resource}/turbo/updated_stream.blade.php` |
-| `deleted` | `{resource}/turbo/deleted_stream.blade.php` |
+```blade
+@if (session()->has('status'))
+<turbo-stream target="notice" action="append">
+    <template>
+        @include('layouts._flash')
+    </template>
+</turbo-stream>
+@endif
+```
 
-**Note: these will only be used when you're using the `response()->turboStream()` macro.**
+I hope you can see how powerful this can be to reusing views.
 
 <a name="broadcasting"></a>
 ### Broadcasting Turbo Streams Over WebSockets With Laravel Echo
@@ -640,7 +645,6 @@ public function store()
 
 You may also catch the `ValidationException` and return a non-200 response, if you want to.
 
-
 <a name="turbo-native"></a>
 ### Turbo Native
 
@@ -739,7 +743,7 @@ class CreatesCommentsTest extends TestCase
 }
 ```
 
-**Note: make sure your `turbo-laravel.queue` config key is set to false, otherwise actions may not be dispatched during test because the model observer only fires them after the transaction is commited, which never happens in tests since they run inside a transaction.**
+*Note: make sure your `turbo-laravel.queue` config key is set to false, otherwise actions may not be dispatched during test because the model observer only fires them after the transaction is commited, which never happens in tests since they run inside a transaction.*
 
 <a name="closing-notes"></a>
 ### Closing Notes