Skip to content

Commit

Permalink
DOC Update typehints in docs (#569)
Browse files Browse the repository at this point in the history
  • Loading branch information
GuySartorelli authored Aug 27, 2024
1 parent 9b76456 commit ced3de0
Show file tree
Hide file tree
Showing 3 changed files with 24 additions and 5 deletions.
2 changes: 1 addition & 1 deletion en/02_Developer_Guides/01_Templates/01_Syntax.md
Original file line number Diff line number Diff line change
Expand Up @@ -575,7 +575,7 @@ use Page;

class HomePage extends Page
{
public function forTemplate()
public function forTemplate(): string
{
// We can also render a template here using $this->renderWith()
return 'Page: ' . $this->Title;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -284,7 +284,7 @@ class Product extends DataObject implements CMSPreviewable
{
// ...

public function forTemplate()
public function forTemplate(): string
{
// If the template for this DataObject is not an "Include" template, use the appropriate type here
// e.g. "Layout".
Expand Down
25 changes: 22 additions & 3 deletions en/08_Changelogs/6.0.0.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,14 +11,16 @@ title: 6.0.0 (unreleased)
- [Changes to default cache adapters](#caching)
- [Changes to scaffolded form fields](#scaffolded-fields)
- [`SiteTree` uses form field scaffolding](#sitetree-scaffolding)
- [Other new features](#other-new-features)
- [Changes to the templating/view layer](#view-layer)
- [Other new features and small changes](#other-new-features)
- [Dependency changes](#dependency-changes)
- [`intervention/image` has been upgraded from v2 to v3](#intervention-image)
- [Bug fixes](#bug-fixes)
- [API changes](#api-changes)
- [Most extension hook methods are now protected](#hooks-protected)
- [Strict typing for `Factory` implementations](#factory-strict-typing)
- [General changes](#api-general)
- [Full list of removed and changed API (by module, alphabetically)](#api-removed-and-changed)

## Features and enhancements

Expand Down Expand Up @@ -181,12 +183,27 @@ SilverStripe\UserForms\Model\UserDefinedForm:
</details>
### Other new features
### Changes to the templating/view layer {#view-layer}
- Native indexed PHP arrays can now be passed into templates and iterated over with `<% loop $MyArray %>`. Under the hood they are wrapped in [`ArrayList`](api:SilverStripe\View\ViewableData), so you can get the count using `$Count` and use `<% if $ArrayList %>` as a shortcut for `<% if $ArrayList.Count %>`. Other functionality from `ArrayList` such as filtering and sorting cannot be used on arrays since they don't have keys to filter or sort against.
#### Strong typing for `ViewableData` and `DBField`

Many of the properties and methods in [`ViewableData`](api:SilverStripe\View\ViewableData), [`DBField`](api:SilverStripe\ORM\FieldType\DBField), and their immediate subclasses have been given strong typehints. Previously, these only had typehints in the PHPDoc which meant that any arbitrary values could be assigned or returned.

Most of the strong types are either identical to the old PHPDoc types, or match what was already actually being assigned to, passed into, and returned from those APIs.

In some cases, where a string was expected but sometimes `null` was being used, we have explicitly strongly typed the API to `string`. This matches [similar changes PHP made in PHP 8.1](https://php.watch/versions/8.1/internal-func-non-nullable-null-deprecation) and will help avoid passing `null` values in to functions that expect a string.

The one change we specifically want to call out is for [`ViewableData::obj()`](api:SilverStripe\View\ViewableData::obj()). This method will now explicitly return `null` if there is no field, property, method, etc to represent the field you're trying to get an object for. This is a change from the old behaviour, where an empty `DBField` instance would be returned even though there's no way for any non-null value to be available for that field.

See the [full list of removed and changed API](#api-removed-and-changed) to see all of the API with updated typing.

### Other new features and small changes {#other-new-features}

- Native indexed PHP arrays can now be passed into templates and iterated over with `<% loop $MyArray %>`. Under the hood they are wrapped in [`ArrayList`](api:SilverStripe\ORM\ArrayList), so you can get the count using `$Count` and use `<% if $ArrayList %>` as a shortcut for `<% if $ArrayList.Count %>`. Other functionality from `ArrayList` such as filtering and sorting cannot be used on arrays since they don't have keys to filter or sort against.
- Modules no longer need to have a root level `_config.php` or `_config` directory to be recognised as a Silverstripe CMS module. They will now be recognised as a module if they have a `composer.json` file with a `type` of `silverstripe-vendormodule` or `silverstripe-theme`.
- A new [`DataObject::getCMSEditLink()`](api:SilverStripe\ORM\DataObject::getCMSEditLink()) method has been added, which returns `null` by default. This provides more consistency for that method which has previously been inconsistently applied to various subclasses of `DataObject`. See [managing records](/developer_guides/model/managing_records/#getting-an-edit-link) for more details about providing sane values for this method in your own subclasses.
- The `CMSEditLink()` method on many `DataObject` subclasses has been renamed to `getCMSEditLink()`.
- Previously if an invalid default value was provided for a [`DBDecimal`](api:SilverStripe\ORM\FieldType\DBDecimal) database column, it would silently set the defalt value to `0`. This will now throw an exception instead, so that you're aware your configured value is invalid and can correct it.

## Dependency changes

Expand Down Expand Up @@ -322,6 +339,8 @@ Injector::inst()->load([
- [`FieldList`](api:SilverStripe\Forms\FieldList) is now strongly typed. Methods that previously allowed any iterable variables to be passed, namely [`FieldList::addFieldsToTab()`](api:SilverStripe\Forms\FieldList::addFieldsToTab()) and [`FieldList::removeFieldsFromTab()`](api:SilverStripe\Forms\FieldList::removeFieldsFromTab()), now require an array to be passed instead.
- [`BaseElement::getDescription()`](api:DNADesign\Elemental\Models\BaseElement::getDescription()) has been removed. If you had implemented this method in your custom elemental blocks, either set the [`description`](api:DNADesign\Elemental\Models\BaseElement->description) configuration property or override the [`getTypeNice()`](api:DNADesign\Elemental\Models\BaseElement::getTypeNice()) method.

### Full list of removed and changed API (by module, alphabetically) {#api-removed-and-changed}

<!--- Changes below this line will be automatically regenerated -->

<!--- Changes above this line will be automatically regenerated -->

0 comments on commit ced3de0

Please sign in to comment.