Migrate from Sage 9 to Sage 10

Hello,
First of all, I want to express my gratitude for this project and all its participants.

Also, I know this question has been asked a few times. I could find 3 topics on the Discourse asking the same question that I have : How to migrate from Sage 9 to Sage 10?

The answers given by the Roots.io devs basically explain that this is not something you should do, that Sage isn’t meant to be upgraded. I understand the big differences between the two versions, and the reason why it’s not really upgradable and why there’s no documentation about it.

But I’d really like to do this upgrade to save some time in the long run. PHP8 was already a struggle to use with Sage 9 due to illuminate incompatibilities, and waiting for another few years will just make the upgrade even harder to do.

I’ve seen some people on the Discourse succeeding doing this upgrade but never explaining how they did it. Can anyone give me a general bullet list of the steps to do? And how to turn the Controllers into Composers?

Thanks in advance for your answers and have a nice day! :slight_smile:

1 Like

Hi,

I might not recall everything.
What I do recall is that, I initially tried to progressively upgrade my Sage 9 theme to 10, by comparing both themes, but that failed right away :rofl:

Then, I started from scratch with a Sage 10 theme, and:

  1. Initially copy over the views that didn’t need much changes - the ones that didn’t call code outside of that scope
  2. Copied over hooks
  3. Copied over my helpers.php file - which was later on deleted after moving functions to composers
  4. And lastly, went file-by-file and copied over only the code that was needed

The last step was definitely the hardest one.

Hope it helps.
Good luck :four_leaf_clover:

1 Like

Thanks so much for your answer @matapatos .
I tried following your guide. I’m stuck on your step 3, because I’m not able to move the functions from the helpers.php to Composers.

I’m getting the error “Class “Roots\Sage\Container” not found”. After some research, I understood that the sage() function isn’t used anymore in Sage 10.

If I understand correctly, I don’t need the sage() function anymore. So I removed it, and I created a Composer for each of the other functions of my helpers.php file. And then, how do I register these Composers? Do I need to create a app/providers/AppServiceProvider.php file? Or are Composers registered automatically?

Here’s my helpers.php code :

<?php

namespace App;

use Roots\Sage\Container;

/**
 * Get the sage container.
 *
 * @param string $abstract
 * @param array  $parameters
 * @param Container $container
 * @return Container|mixed
 */
function sage($abstract = null, $parameters = [], Container $container = null)
{
    $container = $container ?: Container::getInstance();
    if (!$abstract) {
        return $container;
    }
    return $container->bound($abstract)
        ? $container->makeWith($abstract, $parameters)
        : $container->makeWith("sage.{$abstract}", $parameters);
}


/**
 * Get / set the specified configuration value.
 *
 * If an array is passed as the key, we will assume you want to set an array of values.
 *
 * @param array|string $key
 * @param mixed $default
 * @return mixed|\Roots\Sage\Config
 * @copyright Taylor Otwell
 * @link https://github.com/laravel/framework/blob/c0970285192483ab40525a34a71f346f4e43e0e9/src/Illuminate/Foundation/helpers.php#L254-L265
 */
function config($key = null, $default = null)
{
    if (is_null($key)) {
        return sage('config');
    }
    if (is_array($key)) {
        return sage('config')->set($key);
    }
    return sage('config')->get($key, $default);
}


/**
 * Retrieve path to a compiled blade view
 * @param $file
 * @param array $data
 * @return string
 */
function template_path($file, $data = [])
{
    return sage('blade')->compiledPath($file, $data);
}

/**
 * @param $asset
 * @return string
 */
function asset_path($asset)
{
    return sage('assets')->getUri($asset);
}

Here’s an example of one of the Composers I created, for example the one for the config() function :

<?php

namespace App\View\Composers;

use Roots\Acorn\View\Composer;

class ConfigComposer extends Composer
{
    protected static $views = [
        '*', // Apply to all views; you can specify particular views if needed
    ];

    public function with()
    {
        return [
            'config' => function ($key = null, $default = null) {
                return $this->container->get('config')->get($key, $default);
            },
        ];
    }
}

You can also find a screenshot of my errors as an attachment. Thanks in advance for your help everyone!

Yes, composers are automatically registered - there is also a CLI command to create them. You just need to make sure that the $views attribute contains the correct view.

You shouldn’t need that config function anymore, or even the other ones (asset_path, etc). You should now use the Laravel helpers instead - I sent you Laravel 9.x which is currently used in Acorn 3.x but if you use Acorn 2.x you should take a look at Laravel version 8.x.

Note: Not all functions work, but config(), resource_path(), asset() and others does work. You can take a look at the supported components to have an idea of what does work

1 Like

The main use of app/helpers.php is to create functions that “help” your code. They removed it because from a object oriented programming is better to use classes, contracts, etc… than just simple functions inside a code. If you still prefer functions, is fine, you can create a helpers.php file and include it in setup.php for example.

So, to do the migration, what I recommend you is that you don’t take into account anything in helpers.php before line 138. If you added a function after this line, this is what you want to still be in the code.

Maybe another good approach is that you do a kdiff3 of your project against a new empty Sage 9 project. This way, you will know what was changed against the starter theme, and just adapt these changes into a new Sage 10 project from scratch.

Composers, for example, are only required if you used controllers in your previous project. If you didn’t create any controller for a custom functionality, you don’t need to migrate the starter files.

Also, to have more quality information, I recommend that you check laravel and laracasts. Most Sage 10 functionality is exquisitely explained in laravel documentation.

I hope it helps!

2 Likes