Skip to main content
Version: 10.x

Upgrade Guide

Upgrade from 9.0 to 10.0​

Changes in v10 are so drastic that there was no way we could provide an upgrade guide for it.
We suggest that you see the v10 release notes and upgrade your project using it.

Upgrade from 8.0 to 9.0​

Estimated upgrading time: 30 minutes.

  1. Follow the steps in the Manual Upgrading Guide below.

You can view all changes here.

  • Running php artisan apiato should return 9.0.0
  • Running php artisan -V should return 7.*.*

Upgrade from 7.4 to 8.0​

Estimated upgrading time: 30 minutes.

  1. Move the WePay Container away until the upgrade is done, or delete it if you're not using it. This container was removed in Apiato 8.0.

  2. Follow the steps in the Manual Upgrading Guide below.

  3. Use .test instead of .develop for the URL's.

Upgrade from 7.3 to 7.4​

Estimated upgrading time: 30 minutes.

IMPORTANT NOTE 1 : Before upgrading, please review all of your own dependencies, if respective "Laravel 5.6 compatible versions" are already published!

IMPORTANT NOTE 2 : Before upgrading, please git commit all of your changes in order to rollback if something breaks!

Key Changes:

  • Apiato now requires PHP 7.1.3 to run - this is because of Laravel's dependency!
  • Added Laravel 5.6. See the Laravel Upgrade Guide for more details.

Most of the changes introduced by Laravel 5.6 are easy to integrate. However, the following might be a BREAKING CHANGE to your application. Please review the following changes with caution:

Database: Index Order Of Morph Columns

The indexing of the columns built by the morphs migration method has been reversed for better performance. If you are using the morphs method in one of your migrations, you may receive an error when attempting to run the migration's down method. If the application is still in development, you may use the migrate:fresh command to rebuild the database from scratch. If the application is in production, you should pass an explicit index name to the morphs method.

Manual Tasks to do:

  • Update your own dependencies to new L5.6 compatible versions!
  • Add the new LOG_CHANNEL=stack to your environment file.
  • Copy the 2 new Laravel config files (hashing.php and logging.php) to /config/ folder in your main project tree.
  • Adjust the TrustProxies in App/Ship/Middlewares accordingly.
  • Check, if the described "breaking change" may affect your application!
  • Check (and eventually manually set) the dependency to apiato/core : 2.4.* in your App/Ship/composer.json file

Use the Manual Upgrading Guide below.

Upgrade from 7.2 to 7.3​

Estimated upgrading time: 20 minutes.

Use the Manual Upgrading Guide below.

Upgrade from 7.1 to 7.2​

Estimated upgrading time: 10 minutes.

Use the Manual Upgrading Guide below.

Upgrade from 7.0 to 7.1​

Estimated upgrading time: 45 minutes.

Use the Manual Upgrading Guide below.

Upgrade from 5.0 to 7.0​

Estimated upgrading time: 30 minutes.

By upgrading to Apiato 7.0 you can benefit from all the features provided by Laravel 5.5.

This upgrade is simple.

You just have to do the following changes found at the GitHub Comparison Tool.

Note: Some of the files are not required to be upgraded. And some of them, can be simply replaced by the new files (copy a file content from the Apiato repository and replace it with your older version).

Hint: You can do a git merge and solve the conflicts, if you don't want to manually do the changes commit by commit.

Important Information: Laravel 5.5 introduces an auto-discovery feature that lets you automatically register ServiceProviders. Due to the nature and structure of Apiato applications, this features is turned off, because it messes up how config files are loaded in apiato. This means, that you still need to manually register 3rd-party ServiceProviders in the ServiceProvider of a Container. (This should be a temporary situation)

Upgrade from 4.1 to 5.0​

Estimated upgrading time: 15 minutes.

This guide will show you how to freshly install the new Apiato 5.0, then migrate your old project (built with Apiato 4.1) to the freshly installed one (Apiato 5.0).

In the guide we'll be using the term Old Project (referring to your old project that was built with Apiato 4.1), and the term New Project (referring to the new freshly installed Apiato 5.0).

  1. Download and install Apiato 5.0. See Application Setup.

  2. Delete the Containers directory app/Containers from the new project.

  3. Move the Containers directory app/Containers from the old project to the new project.

  4. Open this file app/Ship/composer.json in your old project and only copy the required dependencies, from the old project to the same file in the new project.

  5. Again, open the app/Ship/composer.json file in the new project, and remove the following dependencies: guzzlehttp/guzzle, prettus/l5-repository, barryvdh/laravel-cors, spatie/laravel-fractal, vinkla/hashids and johannesschobel/apiato-container-installer.

  6. Move and replace the following directories from the old project to the new project: config, public, resources, database and storage.

  7. Open config/app.php and replace App\Ship\Engine\Providers\PortoServiceProvider::class with Apiato\Core\Providers\ApiatoProvider::class.

  8. Move .gitignore, phpunit.xml and .env files, from the old project to the new project.

  9. Open the .env file on the new project and append this to it API_RATE_LIMIT_ENABLED=true.

  10. Open phpunit.xml file of the new project and delete this line from the file <file>./app/Ship/Engine/Loaders/FactoryMixer/FactoriesLoader.php</file>.

  11. If you had live testing data in your old project inside app/Ship/Seeders/Data/Testing/Seeders/TestingDataSeeder.php file, then copy that file content and past it in the new project inside app/Ship/Seeders/SeedTestingData.php. You will need to rename the class (not the file) from TestingDataSeeder to SeedTestingData, and you will need to update the namespace from namespace App\Ship\Seeders\Data\Testing\Seeders; to namespace App\Ship\Seeders;.

  12. If you ever used the HashIdTrait, you need to search and replace this namespace App\Ship\Engine\Traits\HashIdTrait with this Apiato\Core\Traits\HashIdTrait.

  13. Run composer update. If you got any error at this step, try to solve it or open an Issue.

  14. Move the .git directory from the old project to the new one. Add all changes git add . then commit git commit -m 'upgrade Apiato from 4.1 to 5.0'.

  15. Run your tests vendor/bin/phpunit.

That's it :)

How to manually upgrade older versions to 4.1?​

Use the Manual Upgrading Guide below.

Manual Upgrading Guide​

These commands and examples, are compatible with the Apiato 8.0 upgrade. You can just copy/past.

  1. Checkout a new branch from your stable branch, to perform the upgrade.
git checkout -b upgrade-apiato
  1. Configure a new remote (upstream) that points to the official Apiato repository.
git remote add upstream https://github.com/apiato/apiato

Verify the new upstream repository was added, by listing the current configured remote repositories.

git remote -vv

origin      [email protected]:username/my-awesome-api.git (fetch)
origin      [email protected]:username/my-awesome-api.git (push)
upstream    [email protected]:apiato/apiato.git (fetch)
upstream    [email protected]:apiato/apiato.git (push)
  1. Checkout a new branch to hold the latest Apiato changes. This branch will be merged into your upgrade-apiato branch created above.
git checkout -b apiato-{version}
// Example:   git checkout -b apiato-8.0
  1. Configure this branch to track an upstream specific branch.

Replace {upstream-branch-name} with the branch name you want to upgrade to (for example 8.0).

git fetch upstream {upstream-branch-name}
// Example:   git fetch upstream 8.0

git branch --set-upstream-to upstream/{upstream-branch-name}
// Example:   git branch --set-upstream-to upstream/8.0

Verify your local branch is tracking the Apiato specified upstream branch.

git branch -vv

 apiato          77b4d945 [upstream/{upstream-branch-name}] ...
 master          77d302aa [origin/master] ...
  1. Make this branch identical to the remote upstream branch
git reset --hard upstream/{upstream-branch-name}
// Example:   git reset --hard upstream/8.0

Verify this branch now contains the latest changes from the upstream branch.

git log
  1. Switch back to the upgrade-apiato branch
git checkout upgrade-apiato
  1. Now lets merge the 2 branches. This step can be done in two ways:

Option A: Merge all the changes together and solve the conflicts if any. (Recommended)

You can execute the next command with different different parameters, below are 2 options to pick whatever feels safer to you. Do not execute both of them.

A1: This will overwrite your changes with the upstream changes. (Try this first and if your tests failed then you can try the second one).

git merge --allow-unrelated-histories --strategy-option=theirs apiato-{version}
// Example:   git merge --allow-unrelated-histories --strategy-option=theirs apiato-8.0

A2: This will let you solve all the conflicts manually. (Can be the most secure choice, but it's time consuming as well.)

git merge --allow-unrelated-histories apiato-{version}
// Example:   git merge --allow-unrelated-histories apiato-8.0

Option B: Manually cherry pick the commits you likes to have:

git log {upstream-branch-name}

(copy each commit ID, one by one)

git cherry-pick {commit-ID}

(if you get any conflict solve it and keep moving)

  1. Compare your .env with the new .env-example and update it.

  2. Check everything is working. By running Composer install first then re-running your tests.

  • Read the changelog releases page.
  • You may want to update your custom containers dependencies, simply follow the composer install error outputs and bump each failing dependency. (Hint: visit each package releases page, and use the version which supports the supported version of Laravel).
  • You may need to fix the failing tests.
composer install  &&  vendor/bin/phpunit
  1. Finally, merge the upgrade-apiato (which contains the upgraded changes) with your stable branch (could be master).
git checkout master
git merge upgrade-apiato

php artisan -V

Enjoy :)