|
| 1 | +# Upgrade Guide |
| 2 | + |
| 3 | +[[toc]] |
| 4 | + |
| 5 | +## Upgrading to 2.x from 1.x |
| 6 | + |
| 7 | +Version 2.0 adds support for PHP 8.1, and supports both Laravel 8 and 9. |
| 8 | +Although we had to make some breaking changes to support PHP 8.1, these will |
| 9 | +not affect the majority of applications. You should therefore find you can |
| 10 | +upgrade very quickly to the new version. |
| 11 | + |
| 12 | +This chapter provides details of the main changes that in theory could affect |
| 13 | +applications. |
| 14 | + |
| 15 | +### Updating Dependencies |
| 16 | + |
| 17 | +#### Laravel Version |
| 18 | + |
| 19 | +If you are still on Laravel 8, the minimum supported version is now `8.76`. |
| 20 | +Ensure you are on at least this version before upgrading. |
| 21 | + |
| 22 | +#### Composer Dependencies |
| 23 | + |
| 24 | +To upgrade, first run the following commands: |
| 25 | + |
| 26 | +```bash |
| 27 | +composer require laravel-json-api/laravel --no-update |
| 28 | +composer require laravel-json-api/testing --dev --no-update |
| 29 | +``` |
| 30 | + |
| 31 | +Then if you have installed any of the following optional packages, run the |
| 32 | +appropriate command from the following: |
| 33 | + |
| 34 | +```bash |
| 35 | +composer require laravel-json-api/hashids --no-update |
| 36 | +composer require laravel-json-api/non-eloquent --no-update |
| 37 | +composer require laravel-json-api/cursor-pagination --no-update |
| 38 | +composer require laravel-json-api/boolean-softdeletes --no-update |
| 39 | +``` |
| 40 | + |
| 41 | +Then finally run the following command to updated all the dependencies: |
| 42 | + |
| 43 | +```bash |
| 44 | +composer up laravel-json-api/* cloudcreativity/* |
| 45 | +``` |
| 46 | + |
| 47 | +### PHP Return Types |
| 48 | + |
| 49 | +PHP is beginning to transition to requiring return type definitions on PHP |
| 50 | +methods such as `offsetGet`, `offsetSet`, etc. In light of this, Laravel |
| 51 | +JSON:API has implemented these return types in its code base. Typically, |
| 52 | +this should not affect user written code; however, if you are overriding one |
| 53 | +of these methods by extending Laravel JSON:API's classes, you will need to add |
| 54 | +these return types to your own application. |
| 55 | + |
| 56 | +### Servers |
| 57 | + |
| 58 | +Previously `Server` classes had a protected `$app` property, that you could use |
| 59 | +to access the application instance. This property is now private. If you are |
| 60 | +accessing it via `$this->app` in your `Server` class, you should now use the |
| 61 | +`$this->app()` method instead. |
| 62 | + |
| 63 | +### Eloquent Fields |
| 64 | + |
| 65 | +PHP 8.1 introduced `readonly` as a keyword. Previously the Laravel JSON:API |
| 66 | +Eloquent package had both an interface and a trait called `ReadOnly`. We have |
| 67 | +therefore had to rename this interface and trait. Both are now called |
| 68 | +`IsReadOnly`. |
| 69 | + |
| 70 | +You are only likely to be using either of these if you have written your own |
| 71 | +field classes. In which case, you need to make the following changes: |
| 72 | + |
| 73 | +- `LaravelJsonApi\Eloquent\Contracts\ReadOnly` is now |
| 74 | + `LaravelJsonApi\Eloquent\Contracts\IsReadOnly` |
| 75 | +- `LaravelJsonApi\Eloquent\Fields\Concerns\ReadOnly` is now |
| 76 | + `LaravelJsonApi\Eloquent\Fields\Concerns\IsReadOnly` |
| 77 | + |
| 78 | +### Testing |
| 79 | + |
| 80 | +When upgrading the testing package, we removed some methods that were marked as |
| 81 | +deprecated some time ago. These methods were also not documented in the testing |
| 82 | +chapters, so hopefully you have not been using them. |
| 83 | + |
| 84 | +The removed methods are documented here, just in case: |
| 85 | + |
| 86 | +- The `assertUpdated()` method was removed. Use `assertFetchedOne()` instead, |
| 87 | + as shown in [the example update test.](../testing/resources.md#update-testing) |
| 88 | +- The `assertDeleted()` method was removed. Use `assertNoContent()` or |
| 89 | + `assertMetaWithoutData()` depending on what your delete action returns. See |
| 90 | + [the example delete test if needed.](../testing/resources.md#destroy-aka-delete-testing) |
0 commit comments