mirror of
https://github.com/silverstripe/silverstripe-framework
synced 2024-10-22 14:05:37 +02:00
Merge pull request #6560 from robbieaverill/feature/docs-for-upgrading-tasks-segment
DOCS Add note for $segment in BuildTask to 4.0.0 changelog, switch code blocks to GitHub style
This commit is contained in:
Daniel Hensby
GitHub
commit
60c8996309
@ -64,10 +64,11 @@ as a standard first point of upgrade.
|
||||
Nearly all core PHP classes have been namespaced. For example, `DataObject` is now called `SilverStripe\ORM\DataObject`.
|
||||
We have developed an [upgrader tool](https://github.com/silverstripe/silverstripe-upgrader/) to (semi-)automatically update your 3.x code to the new naming. Here's an example how to upgrade your `mysite` folder:
|
||||
|
||||
```
|
||||
composer global require silverstripe/upgrader
|
||||
cd ~/Project/Root
|
||||
~/.composer/vendor/bin/upgrade-code upgrade ./mysite --write
|
||||
|
||||
```
|
||||
|
||||
If you want to do a dry-run, omit the `--write` option to see a preview of a diff of
|
||||
all changed project files.
|
||||
@ -176,34 +177,33 @@ explicitly cast for that field.
|
||||
|
||||
You can resolve this in your model by adding an explicit cast to HTML for those fields.
|
||||
|
||||
|
||||
Before:
|
||||
|
||||
|
||||
:::php
|
||||
```php
|
||||
class MyObject extends ViewableData {
|
||||
public function getSomeHTML {
|
||||
$title = Convert::raw2xml($this->Title);
|
||||
return "<h1>{$title}</h1>";
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
After:
|
||||
|
||||
|
||||
:::php
|
||||
class MyObject extends ViewableData {
|
||||
```php
|
||||
class MyObject extends ViewableData
|
||||
{
|
||||
private static $casting = [
|
||||
'SomeHTML' => 'HTMLText'
|
||||
];
|
||||
|
||||
public function getSomeHTML {
|
||||
public function getSomeHTML
|
||||
{
|
||||
$title = Convert::raw2xml($this->Title);
|
||||
return "<h1>{$title}</h1>";
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
If you need to encode a field (such as HTMLText) for use in html attributes, use `.ATT`
|
||||
instead, or if used in an actual XML file use `.CDATA` (see [template casting](/developer_guides/templates/casting)).
|
||||
@ -225,9 +225,10 @@ In order to retain existing file paths in line with framework version 3 you shou
|
||||
Note that this will not allow you to utilise certain file versioning features in 4.0.
|
||||
|
||||
|
||||
:::yaml
|
||||
\SilverStripe\Filesystem\Flysystem\FlysystemAssetStore:
|
||||
```
|
||||
SilverStripe\Filesystem\Flysystem\FlysystemAssetStore:
|
||||
legacy_paths: true
|
||||
```
|
||||
|
||||
|
||||
See our ["File Management" guide](/developer_guides/files/file_management) for more information.
|
||||
@ -241,10 +242,10 @@ this task is run manually during an explicit migration process, as this process
|
||||
large amounts of memory and run for an extended time.
|
||||
|
||||
|
||||
:::yaml
|
||||
```yaml
|
||||
File:
|
||||
migrate_legacy_file: true
|
||||
|
||||
```
|
||||
|
||||
This task will also support migration of existing File DataObjects to file versioning. Any
|
||||
pre-existing File DataObjects will be automatically published to the live stage, to ensure
|
||||
@ -273,32 +274,30 @@ is intended to upload images for manipulation.
|
||||
|
||||
Before:
|
||||
|
||||
|
||||
:::php
|
||||
```php
|
||||
if($file instanceof Image) {
|
||||
$upload = new UploadField();
|
||||
$upload->setAllowedFileCategories('image');
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
After:
|
||||
|
||||
|
||||
:::php
|
||||
```php
|
||||
if ($file->getIsImage()) {
|
||||
$upload = new UploadField();
|
||||
$upload->setAllowedFileCategories('image/supported');
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
In cases where image-only assets may be assigned to relationships then your datamodel should specify explicitly
|
||||
an `Image` datatype, or refer to `DBFile('image/supported')`.
|
||||
|
||||
E.g.
|
||||
|
||||
|
||||
:::php
|
||||
class MyObject extends DataObject {
|
||||
```php
|
||||
class MyObject extends DataObject
|
||||
{
|
||||
private static $has_one = array(
|
||||
"ImageObject" => "Image"
|
||||
);
|
||||
@ -306,7 +305,7 @@ E.g.
|
||||
"ImageField" => "DBFile('image/supported')"
|
||||
);
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
#### Upgrading code that writes to `File` dataobjects, or writes files to the 'assets' folder
|
||||
|
||||
@ -321,27 +320,27 @@ You would need to upgrade your code as below.
|
||||
Before:
|
||||
|
||||
|
||||
:::php
|
||||
```php
|
||||
function importTempFile($tmp) {
|
||||
copy($tmp, ASSETS_PATH . '/imported/' . basename($tmp));
|
||||
$file = new File();
|
||||
$file->setFilename('assets/imported/'.basename($tmp));
|
||||
$file->write();
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
After:
|
||||
|
||||
|
||||
:::php
|
||||
function importTempFile($tmp) {
|
||||
```php
|
||||
public function importTempFile($tmp)
|
||||
{
|
||||
Versioned::reading_stage('Stage');
|
||||
$file = new File();
|
||||
$file->setFromLocalFile($tmp, 'imported/' . basename($tmp));
|
||||
$file->write();
|
||||
$file->doPublish();
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Note that 'assets' is no longer present in the new code, and the path beneath what was once assets is now
|
||||
used to generate the 'filename' value. This is because there is no longer an assumption that files are
|
||||
@ -356,12 +355,11 @@ There are other important considerations in working with File dataobjects which
|
||||
to the public site. You will need to make sure to invoke `->doPublish()` on any File DataObject
|
||||
you wish visitors to be able to see.
|
||||
|
||||
You can disable File versioning by adding the following to your _config.php
|
||||
You can disable File versioning by adding the following to your `_config.php`
|
||||
|
||||
|
||||
:::php
|
||||
```php
|
||||
File::remove_extension('Versioned');
|
||||
|
||||
```
|
||||
|
||||
#### Upgrading code performs custom image manipulations
|
||||
|
||||
@ -375,29 +373,33 @@ For instance, code which sizes images to a fixed width should be updated as belo
|
||||
|
||||
Before:
|
||||
|
||||
|
||||
:::php
|
||||
```php
|
||||
// in MyImageExtension.php
|
||||
class MyImageExtension extends DataExtension {
|
||||
public function GalleryThumbnail($height) {
|
||||
class MyImageExtension extends DataExtension
|
||||
{
|
||||
public function GalleryThumbnail($height)
|
||||
{
|
||||
return $this->getFormattedImage('GalleryThumbnail', $height);
|
||||
}
|
||||
public function generateGalleryThumbnail(Image_Backend $backend, $height) {
|
||||
|
||||
public function generateGalleryThumbnail(Image_Backend $backend, $height)
|
||||
{
|
||||
return $backend->paddedResize(300, $height);
|
||||
}
|
||||
}
|
||||
|
||||
// in _config.php
|
||||
Image::add_extension('MyImageExtension');
|
||||
|
||||
```
|
||||
|
||||
Now image manipulations are implemented with a single method via a callback generator:
|
||||
|
||||
|
||||
:::php
|
||||
```php
|
||||
// in MyImageExtension.php
|
||||
class MyImageExtension extends Extension {
|
||||
public function GalleryThumbnail($height) {
|
||||
class MyImageExtension extends Extension
|
||||
{
|
||||
public function GalleryThumbnail($height)
|
||||
{
|
||||
// Generates the manipulation key
|
||||
$variant = $this->owner->variantName(__FUNCTION__, $height);
|
||||
|
||||
@ -411,12 +413,12 @@ Now image manipulations are implemented with a single method via a callback gene
|
||||
|
||||
// in _config.php
|
||||
File::add_extension('MyImageExtension');
|
||||
SilverStripe\Filesystem\Storage\DBFile::add_extension('MyImageExtension');
|
||||
|
||||
\SilverStripe\Filesystem\Storage\DBFile::add_extension('MyImageExtension');
|
||||
```
|
||||
|
||||
There are a few differences in this new API:
|
||||
|
||||
* The extension is no longer specific to DataObjects, so it uses the generic 'Extension' class instead of 'DataExtension'
|
||||
* The extension is no longer specific to DataObjects, so it uses the generic `Extension` class instead of `DataExtension`
|
||||
* This extension is added to both `DBFile` and `File`, or order to make this manipulation available to non-dataobject
|
||||
file references as well, but it could be applied to either independently.
|
||||
* A helper method `variantName` is invoked in order to help generate a unique variant key. Custom code may use another
|
||||
@ -432,10 +434,10 @@ that handled saving of content into composite fields can be removed, as it is no
|
||||
|
||||
The below describes the minimum amount of effort required to implement a composite DB field.
|
||||
|
||||
:::php
|
||||
<?
|
||||
class MyAddressField extends DBComposite {
|
||||
|
||||
```php
|
||||
<?php
|
||||
class MyAddressField extends DBComposite
|
||||
{
|
||||
private static $composite_db = array(
|
||||
'Street' => 'Varchar(200)',
|
||||
'Suburb' => 'Varchar(100)',
|
||||
@ -443,11 +445,12 @@ The below describes the minimum amount of effort required to implement a composi
|
||||
'Country' => 'Varchar(100)'
|
||||
);
|
||||
|
||||
public function scaffoldFormField($title = null) {
|
||||
public function scaffoldFormField($title = null)
|
||||
{
|
||||
new AddressFormField($this->getName(), $title);
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
#### Upgrading code that references `DataObject::database_fields` or `DataObject::db`
|
||||
|
||||
@ -483,26 +486,46 @@ fix a table name, to prevent it being changed (for instance, when applying a nam
|
||||
the `table_name` config can be applied to any DataObject class.
|
||||
|
||||
|
||||
:::php
|
||||
```php
|
||||
namespace SilverStripe\BannerManager;
|
||||
class BannerImage extends \DataObject {
|
||||
|
||||
use SilverStripe\ORM\DataObject;
|
||||
|
||||
class BannerImage extends DataObject
|
||||
{
|
||||
private static $table_name = 'BannerImage';
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
In order to ensure you are using the correct table for any class a new [api:DataObjectSchema] service
|
||||
is available to manage these mappings (see [versioned documentation](/developer_guides/model/data_model_and_orm)).
|
||||
|
||||
|
||||
:::php
|
||||
public function countDuplicates($model, $fieldToCheck) {
|
||||
```php
|
||||
public function countDuplicates($model, $fieldToCheck)
|
||||
{
|
||||
$table = DataObject::getSchema()->tableForField($model, $field);
|
||||
$query = new SQLSelect();
|
||||
$query->setFrom("\"{$table}\"");
|
||||
$query->setWhere(["\"{$table}\".\"{$field}\"" => $model->$fieldToCheck]);
|
||||
return $query->count();
|
||||
}
|
||||
```
|
||||
|
||||
#### Upgrade BuildTask classes
|
||||
|
||||
Similarly to the `$table_name` configuration property for DataObjects, you should define a `private static $segment` for `BuildTask`
|
||||
instances to ensure that you can still run your task via `sake dev/tasks/MyTask`. Without defining it, the default
|
||||
will be a fully-qualified class name like `sake dev/tasks/Me-MyModule-Tasks-MyTask`. This can also be configured in YAML.
|
||||
|
||||
```php
|
||||
use SilverStripe\Dev\BuildTask;
|
||||
|
||||
class MyTask extends BuildTask
|
||||
{
|
||||
private static $segment = 'MyTask';
|
||||
}
|
||||
```
|
||||
|
||||
#### Upgrade implementations of augmentSQL
|
||||
|
||||
@ -511,7 +534,7 @@ type will raise a PHP error.
|
||||
|
||||
Before:
|
||||
|
||||
:::php
|
||||
```php
|
||||
function augmentSQL(SQLQuery &$query, DataQuery &$dataQuery = null) {
|
||||
$locale = Translatable::get_current_locale();
|
||||
if(!preg_match('/("|\'|`)Locale("|\'|`)/', implode(' ', $query->getWhere()))) {
|
||||
@ -519,11 +542,13 @@ Before:
|
||||
$query->addWhere($qry);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
After:
|
||||
|
||||
:::php
|
||||
function augmentSQL(SQLSelect $query, DataQuery $dataQuery = null) {
|
||||
```php
|
||||
public function augmentSQL(SQLSelect $query, DataQuery $dataQuery = null)
|
||||
{
|
||||
$locale = Translatable::get_current_locale();
|
||||
if (!preg_match('/("|\'|`)Locale("|\'|`)/', implode(' ', $query->getWhereParameterised($parameters)))) {
|
||||
$query->addWhere(array(
|
||||
@ -531,7 +556,7 @@ After:
|
||||
));
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
#### Upgrade code that modifies the behaviour of ErrorPage
|
||||
|
||||
@ -553,10 +578,11 @@ In case that user code must customise this filename, such as for extensions whic
|
||||
for any error page, the extension point `updateErrorFilename` can be used. This extension point should
|
||||
also be used to replace any `alternateFilepathForErrorcode` used.
|
||||
|
||||
|
||||
:::php
|
||||
class MyErrorPageExtension extends SiteTreeExtension {
|
||||
public function updateErrorFilename(&$name, &$statuscode) {
|
||||
```php
|
||||
class MyErrorPageExtension extends SiteTreeExtension
|
||||
{
|
||||
public function updateErrorFilename(&$name, &$statuscode)
|
||||
{
|
||||
if ($this->owner->exists()) {
|
||||
$locale = $this->Locale;
|
||||
} else {
|
||||
@ -565,17 +591,18 @@ also be used to replace any `alternateFilepathForErrorcode` used.
|
||||
$name = "error-{$statusCode}-{$locale}.html";
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
:::yaml
|
||||
```yml
|
||||
ErrorPage:
|
||||
extensions:
|
||||
- MyErrorPageExtension
|
||||
```
|
||||
|
||||
#### Upgrading asset web.config, .htaccess, or other server configuration
|
||||
|
||||
Server configuration files for `/assets` are no longer static, and are regenerated via a set of
|
||||
standard silverstripe templates on flush. These templates include:
|
||||
standard SilverStripe templates on flush. These templates include:
|
||||
|
||||
* `Assets_HTAccess.ss`: Template for public permissions on the Apache server.
|
||||
* `Assets_WebConfig.ss`: Template for public permissions on the IIS server.
|
||||
@ -610,6 +637,7 @@ of items to disable.
|
||||
|
||||
In Framework 4.0 the user interface for TinyMCE has been trimmed down considerably, with certain toolbar
|
||||
buttons removed from the default cms configuration. These include:
|
||||
|
||||
* Strikethrough
|
||||
* Styles dropdown
|
||||
* Block quotes
|
||||
@ -625,7 +653,7 @@ tinymce config, or by creating custom configurations.
|
||||
The optional `ss_macron` plugin for inserting Māori diacritical marks
|
||||
has been removed from core. You can configure the built-in `charmap` plugin instead:
|
||||
|
||||
:::php
|
||||
```php
|
||||
$editor = HtmlEditorConfig::get('cms');
|
||||
$editor->enablePlugins('charmap');
|
||||
$editor->addButtonsToLine(1, 'charmap');
|
||||
@ -641,9 +669,10 @@ has been removed from core. You can configure the built-in `charmap` plugin inst
|
||||
['333','o - macron'],
|
||||
['363','u - macron']
|
||||
]);
|
||||
```
|
||||
|
||||
For more information on available options and plugins please refer to the
|
||||
[tinymce documentation](https://www.tinymce.com/docs/configure/)
|
||||
[TinyMCE documentation](https://www.tinymce.com/docs/configure/)
|
||||
|
||||
#### Upgrading DataObjects with the `Versioned` extension
|
||||
|
||||
@ -654,26 +683,27 @@ Rather than declaring the list of stages a model has, the constructor for `Versi
|
||||
parameter, which declares whether or not the model is versioned and has a draft and live stage, or alternatively
|
||||
if it only has versioning without staging.
|
||||
|
||||
|
||||
:::php
|
||||
```php
|
||||
/**
|
||||
* This model has staging and versioning. Stages will be "Stage" and "Live"
|
||||
*/
|
||||
class MyStagedModel extends DataObject {
|
||||
class MyStagedModel extends DataObject
|
||||
{
|
||||
private staic $extensions = array(
|
||||
"Versioned('StagedVersioned')"
|
||||
"SilverStripe\\ORM\\Versioning\\Versioned('StagedVersioned')"
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* This model has versioning only, and will not has a draft or live stage, nor be affected by the current stage.
|
||||
*/
|
||||
class MyVersionedModel extends DataObject {
|
||||
class MyVersionedModel extends DataObject
|
||||
{
|
||||
private static $extensions = array(
|
||||
"Versioned('Versioned')"
|
||||
"SilverStripe\\ORM\\Versioning\\Versioned('Versioned')"
|
||||
);
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Additionally, the following api methods have been added:
|
||||
|
||||
@ -721,6 +751,7 @@ An exception to this is any classes which once had the `SS_` prefix, which will
|
||||
|
||||
Before:
|
||||
|
||||
```
|
||||
class MyObject extends DataObject {
|
||||
private static $db = array(
|
||||
'Number' => 'Int',
|
||||
@ -735,12 +766,16 @@ Before:
|
||||
return new Varchar('TextNumber', 'Number is ' . $this->Number);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
After:
|
||||
|
||||
```php
|
||||
use SilverStripe\ORM\DataObject;
|
||||
use SilverStripe\ORM\FieldType\DBVarchar;
|
||||
|
||||
class MyObject extends DataObject {
|
||||
class MyObject extends DataObject
|
||||
{
|
||||
private static $db = array(
|
||||
'Number' => 'Int',
|
||||
'Time' => 'Datetime'
|
||||
@ -750,12 +785,14 @@ After:
|
||||
* @param Int $val
|
||||
* @return Varchar
|
||||
*/
|
||||
public function TextNumber() {
|
||||
public function TextNumber()
|
||||
{
|
||||
return new DBVarchar('TextNumber', 'Number is ' . $this->Number);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Note that string references to SS_Datetime passed to injector, or used in config values, will still work, and will refer to the updated class names.
|
||||
Note that string references to `SS_Datetime` passed to injector, or used in config values, will still work, and will refer to the updated class names.
|
||||
|
||||
#### Upgrading from deprecated RestfulService
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user