3.3 (#704)

* New Antlers docs (#692)

Co-authored-by: Jason Varga <jason@pixelfear.com>

* Update blade doc with new `Statamic::tag()` and `Statamic::modify()` usage. (#702)

* Frontend form field conditions (#691)

* Document conditional fields in front-end forms.

* JS.

* Finish documenting custom JS drivers.

* Suggest more real-world example gist, as well as a link to our built-in Alpine driver.

* Tweak the intro

Co-authored-by: Jack McDade <jack@jackmcdade.com>

* Link to the new parser docs

* Mention alternate closing tags

* Refactor JSON encoding for form attributes in JS drivers (#723)

* fix mobile header overflow issue. Closes #725

* Document newest PHP delimiter

* Show the new new site site in the quick start guide

* Delete installed.png

* initial 3.3 upgrade guide

* Blade variables as per statamic/cms#5201

* fix a few code examples

* change per statamic/cms#5302

* Improve docs on getting data out of entries

* reword

* avoid the slash so the example isn't highlighted as a regex. its just an example.

* wip

* Rely on the automatic TOC

* Update fluent tag docs with param setters (#739)

* zero impact 3.3 changes

* fetch and pagination example

* property access

* explain void

* form submission data change

* live preview

* live preview

* Remove live preview extending page - it's all covered in the regular one

* at symbol can escape braces in strings and params

* Laravel 8

* explain date field change

* Add date where clauses

* laravel upgrade guide

* Tweak the L7-L8 upgrade guide

* A few more tweaks

* fix tpyo

* enh?

* Improve Blade docs

* Remove caveats.

* Routes and Controller examples for Blade

* A little more detail up front

Co-authored-by: Jason Varga <jason@pixelfear.com>
Co-authored-by: Jesse Leite <jesseleite@gmail.com>

app/Modifiers/Toc.php

@@ -55,10 +55,10 @@ private function create($content, $maxHeadingLevels)
             $ret = preg_match('/id=[\'|"](.*)?[\'|"]/i', stripslashes($heading[2]), $anchor);
 
             if ($ret && $anchor[1] != '') {
-                $anchor = stripslashes($anchor[1]);
+                $anchor = trim(stripslashes($anchor[1]));
                 $add_id = false;
             } else {
-                $anchor = preg_replace('/\s+/', '-', preg_replace('/[^a-z\s]/', '', strtolower(strip_tags($heading[3]))));
+                $anchor = preg_replace('/\s+/', '-', trim(preg_replace('/[^a-z\s]/', '', strtolower(strip_tags($heading[3])))));
                 $add_id = true;
             }
 

content/collections/docs/3-2-to-3-3.md

@@ -0,0 +1,280 @@
+---
+id: 4947cda2-d17d-4289-ab37-1f4f64bfa1d4
+blueprint: page
+title: 'Upgrade from 3.2 to 3.3'
+intro: 'A guide for upgrading from 3.2 to 3.3. For most sites, the process will take less than 5 minutes. If your site is running an old version of PHP or Laravel, it may take a bit longer.'
+template: page
+---
+## Overview
+
+First read through this guide to see if there's anything that you might need to adjust. When upgrading, Statamic may automate some things for you. They'll be noted below.
+
+In your `composer.json`, change the `statamic/cms` requirement:
+
+```json
+"statamic/cms": "3.3.*"
+```
+
+Then run:
+
+``` shell
+composer update statamic/cms --with-dependencies
+```
+
+## High impact changes
+
+### PHP >=7.4 required {#php-version}
+
+Statamic 3.3 now requires at least PHP 7.4.
+
+If you're running a lower version, we recommend upgrading all the way to 8.1.
+
+### Laravel 8 required
+
+Statamic 3.3 now requires at least Laravel 8.
+
+If you're running a lower version, we recommend upgrading all the way to 9.
+
+You can check your version of Laravel by running `php artisan -V`.
+
+Find out [how to upgrade from Laravel 7 to Laravel 8](/upgrade-guide/laravel-7-to-8).
+
+## Medium impact changes
+
+### Entries fieldtype augments to query builders {#entries-fieldtype}
+
+The `entries` fieldtype would previously augment to an `EntryCollection` of `Entry` objects. In 3.3, they will augment to a query builder.
+
+#### In Antlers
+
+If you were adding modifiers to your loop, you'll need to apply them to an inner aliased loop.
+
+Before:
+
+```
+{{ related_posts modifier="param" }}
+  ...
+{{ /related_posts }}
+```
+
+After:
+
+```
+{{ related_posts as="whatever" }}
+  {{ whatever modifier="param" }}
+    ...
+  {{ /whatever }}
+{{ /related_posts }}
+```
+
+#### In PHP
+
+If you're using them in PHP, you'll need to add a `->get()` to grab the entries from the query before continuing.
+
+Before:
+
+```php
+$relatedPosts->someCollectionMethod(...);
+```
+
+After:
+
+```php
+$relatedPosts->get()->someCollectionMethod(...);
+```
+
+## Low impact changes
+
+### New Experimental Antlers Parser {#antlers}
+
+3.3 includes an overhauled Antlers parser. It fixes many issues with the existing parser and brings many new features.
+
+By upgrading to 3.3 **you will not automatically get the new parser**.
+
+If you'd like to use the new parser, [read about it in the docs](/new-antlers-parser), where it explains the experimental nature and how to use it.
+
+
+### Date field's time_required setting has been removed {#date-time-required}
+
+The `time_required` option has been removed from the `date` fieldtype.
+The `time_enabled` setting still exists, and we suggest you use that.
+
+
+### v-calendar upgraded to v2 {#v-calendar}
+
+If you were relying on the [v-calendar](https://github.com/nathanreyes/v-calendar) package within the Control Panel, be aware that it has been upgraded to v2.
+
+### Property access on items now performs augmentation
+
+See PR [#5297](https://github.com/statamic/cms/issues/5297) for more details.
+
+Previously if you were to do `$entry->something`, it would get the raw value on the entry. It would _not_ factor in fallbacks from any origin entries, or the collection's injected data. It would _not_ do any augmentation. It would _not_ give you method-based values you might expect automatically in templates (like `id`, `slug`, etc).
+
+In 3.3, doing `$entry->something` will do all of those. It will factor in fallbacks, augment, and give you method based values.
+
+```yaml
+id: 123
+intro: 'hello'   # (a "text" fieldtype)
+foo: 'bar'       # (not even in the blueprint at all)
+content: |       # (a "markdown" fieldtype)
+  # Heading
+  Paragraph
+```
+```php
+// 3.2
+$entry->content; // "# Heading\nParagraph"
+$entry->intro;   // "hello"
+$entry->foo;     // "bar"
+$entry->id;      // null
+$entry->slug;    // null
+$entry->url;     // null
+
+// 3.3
+$entry->content; // "<h1>Heading</h1><p>Paragraph</p>
+$entry->intro;   // "hello"
+$entry->foo;     // "bar"
+$entry->id;      // 123
+$entry->slug;    // "my-entry"
+$entry->url;     // "/blog/my-entry"
+```
+
+On 3.2, property access on terms did nothing. You'd get a warning and null.
+
+
+### Augmentation methods return Value instances {#augmentation-value-instances}
+
+See PR [#5302](https://github.com/statamic/cms/issues/5302) for more details. This change will only affect custom PHP code.
+
+This is considered a low impact change since it should only affect edge cases.
+
+- If you were explicitly coding something expecting a non-`Value`, it will now be a `Value`.
+- If it was being cast to a string or array, no change is needed since the `Value` class knows how to cast itself.
+
+For example, previously `toAugmentedArray()` you'd only get `Value` objects for fields that exist in the blueprint.
+
+```php
+$arr = $entry->toAugmentedArray();
+// [
+//   'published'            => false,
+//   'url'                  => '/blog/my-post'
+//   'some_blueprint_field' => Value('some value'),
+//   ...
+// ]
+
+$inBlog = (Str::startsWith($arr['url'], '/blog')) ? 'yes' : 'no'; // yes
+$isPublished = ($arr['published']) ? 'yes' : 'no'; // 'no'
+```
+
+In 3.3, everything in the array would be wrapped in `Value` objects.
+
+```php
+$arr = $entry->toAugmentedArray();
+// [
+//   'published'            => Value(false),
+//   'url'                  => Value('/my-post')
+//   'some_blueprint_field' => Value('some value'),
+//   ...
+// ]
+
+// ✅ No change. It would cast the Value to a string, giving you the same outcome.
+$inBlog = (Str::startsWith($arr['url'], '/blog')) ? 'yes' : 'no'; // yes
+
+// 🚨 This is changing.
+// Previously it would check "if true/false". But now it's "if object" which will always be true.
+$isPublished = ($arr['published']) ? 'yes' : 'no'; // 'yes'
+```
+
+You'll now need to add `->value()` to get the underlying value.
+
+```php
+$isPublished = ($arr['published']->value()) ? 'yes' : 'no'; // 'yes'
+```
+
+The same goes for other augmentation methods:
+- `$entry->toAugmentedArray()` will only contain `Value` instances.
+- `$entry->toAugmentedCollection()` will only contain `Value` instances.
+- `$entry->augmentedValue('field')` will always return a `Value` instance.
+- `$entry->augmented()->get('field')` will always return a `Value` instance.
+
+But really, the fix would be to avoid the manual augmentation methods entirely and just do `$entry->fieldname`, `$entry->published`, etc.
+
+```php
+$isPublished = ($entry->published) ? 'yes' : 'no'; // 'yes'
+```
+
+### Form submission data is an unfiltered collection
+
+In 3.2, if you did `$submission->data()` you would sometimes get an array, sometimes an `Illuminate\Support\Collection` (the inconsistency was a bug) and any keys that didn't exist in the blueprint would get filtered out.
+
+In 3.3, you will always get a Collection, and it will not have any filtering applied.
+
+### Live Preview
+
+If you're not overriding the `toLivePreviewResponse` in the `Entry` or `Term` classes, there is no change for you.
+
+The `toLivePreviewResponse` methods have been removed in favor of a token based system. You can instead migrate to a dedicated route that will get the Live Preview version of the entry/term via a token.
+
+See the [Live Preview Custom Rendering docs](/live-preview#custom-rendering) for how to do this.
+
+### Custom date fields are now Carbon instances
+
+Custom date fields are now stored in the Stache as `Carbon` instances.
+
+This will only affect you if you're performing a query on a `date` field expecting it to be a string. For instance, `$query->where('datefield', 'like', '2020-%')` or `:datefield:starts_with="2020"`
+
+The actual `date` field on an entry (i.e. the publish date) would have already been a Carbon instance. This only applies to `date` fields that aren't named `date`.
+
+
+## Zero impact changes
+
+These are items that you can completely ignore. They are suggestions on how to improve your code using newly added features.
+
+### You probably don't need to manually augment
+
+If you were manually grabbing an augmented value instance, then getting the actual augmented value from that - you can now just use the magic getters to get the underlying augmented value.
+
+```php
+$entry->augmentedValue('fieldname')->value(); // [tl! --]
+$entry->fieldname; // [tl! ++]
+```
+
+### Leverage relationship magic methods
+
+If you were manually performing a new query based on selections from an entries fieldtype, you can now use the magic method to get a query builder.
+
+```php
+$relatedIds = $entry->get('related_posts'); // [tl! --]
+$selectedFeaturedEntries = Entry::query()->whereIn('id', $relatedIds)->where('featured', true)->get(); // [tl! --]
+$selectedFeaturedEntries = $entry->related_posts()->where('featured', true)->get(); // [tl! ++]
+```
+
+### Use Tags in Blade
+
+If you were using the [Blade Directives](https://github.com/edalzell/statamic-blade) to work with Statamic data in your Blade templates, you can now use a whole bunch of native features instead.
+
+```blade
+@collection('pages', ['title:is' => 'My Title', 'author:is' => 'Erin', 'limit' => 3, 'sort' => 'title:desc']) {{-- [tl! --] --}}
+{{-- [tl! ++:start] --}}
+@foreach (Statamic::tag('collection:pages')
+            ->params(['title:is' => 'My Title', 'author:is' => 'Erin'])
+            ->limit(3)->sort('title:desc')
+            as $entry
+) {{-- [tl! ++:end] --}}
+    @if($entry['no_results']) {{-- [tl! --] --}}
+    @if($entry->no_results) {{-- [tl! ++] --}}
+        <p>There are no results</p>
+    @else
+        {{ $entry['title'] }} {{-- [tl! --] --}}
+        {{ $entry->title }} {{-- [tl! ++] --}}
+    @endif
+@endcollection
+```
+
+```php
+return [
+  'providers' => [
+    Edalzell\Blade\Augmentation\AugmentationViewServiceProvider::class, // [tl!--]
+    Illuminate\View\ViewServiceProvider::class, // [tl!++]
+  ]
+]
+```

content/collections/docs/antlers.md

@@ -1,6 +1,11 @@
 ---
 title: 'Antlers Templates'
-intro: 'Antlers is a simple and powerful templating engine provided with Statamic.  It can fetch and filter content, display and modify data, tap into core features like user authentication and search, and handle complex logic.'
+intro: >
+  Antlers is a simple and powerful templating engine provided with Statamic.  It can fetch and filter content, display and modify data, tap into core features like user authentication and search, and handle complex logic.
+
+  :::warning New Hotness Alert!
+    Statamic 3.3 introduces a [brand new, rewritten, opt-in Antlers Parser](/new-antlers-parser) jam packed with new features, performance improvements, and bug fixes. Check it out! Try it out!
+  :::
 blueprint: page
 template: page
 id: dcf80ee6-209e-45aa-af42-46bbe01996e2