Chartjs Upgrade Guide

We've provided an upgrade path based on the most common Laravel setups with Chartjs. This guide assumes that you are using Chartjs through a Laravel package, currently running Chartjs version 2 and wanting to move to Chartjs 3 or 4.

Step 1 - Upgrade the Laravel Package

1. Before making any changes, create a backup of your current Laravel project to avoid potential data loss or code issues.

2. To migrate to the new Laravel Chartjs package, we need to remove the old composer dependency (varies depending on your current setup):

composer remove fx3costa/laravelchartjs

composer remove vitopedro/laravel-chartjs

3. Install the current version of the new Laravel Chartjs package. To get started you will want to mirror your current setup as closely as possible (eg same delivery method, date adapters, etc) so you may also want to publish the config file and use the available settings to match your current setup.

composer require icehouse-ventures/laravel-chartjs

3. Check that charts are working on the new package. Verify that your charts are functioning as expected with the new package. Address any compatibility issues or errors that may arise during this process.

Step 2 - Update Chartjs Version

1. Use the config variable in config\chartjs.php to update the Chartjs version that the package is loading for you.

2. Update your delivery method in the config file to deliver the target version you are moving to. You can use binary or CDN for easy testing across multiple Chartjs versions.

Step 3 - Update Chartjs plugins

1. Check if your charts rely on specific adapters or plugins (usually shown as an error in the browser console), such as Moment.js or Numeral.js. Update or install these components to versions compatible with the target Chartjs version.

2. Javacript packages such as Chartjs often rely on a third-party package to manage dates, timezones and date formatting (similar to how we use Carbon in Laravel). Moment.js has been deprecated so we provide a CDN pathway for toggling the date plugins (and the relevant adapter) between Moment.js, Luxon.js or date-fns.js. The date-fns is popular and lightweight but we've found that Luxon is a more natural drop-in replacement for Moment because it uses a similar date syntax.

Step 4 - Update Scale syntax

1. The official migration guides for Chartjs versions include instructions for specific versions and options that need to be checked. For common Laravel Chartjs usage, the key changes needed are most likely to be scales and tooltips.

2.When moving from Chartjs version 2 up to version 3 or above the naming and array syntax for scales have changed. Scale option keys can be updated by running a find and replace or refactor on your code base. You will also need to update the scale 'grouping' syntax from the Chartjs version 2 (which used square brackets). In Chartjs 3 and above the scale options uses curly braces.

// Version 2
->optionsRaw("{
    scales: {
        xAxes: [{
            // x-axis options here
        }],
        yAxes: [{
            // y-axis options here
        }]
    }
}");

// Version 3
->optionsRaw("{
    scales: {
        x: {
            // x-axis options here
        },
        y: {
            // y-axis options here
        }
    }
}");

Step 5 - Update Tooltip syntax

1. The namespace for chart hover-over data labels (called tooltips in Chartjs) has moved from options->tooltips to options->plugins->tooltip (note the change to singular). And the data that the tooltip should reference for a callback (mini Javascript functions) has moved from dataset->data to context->dataset->data

// Version 2
->optionsRaw("{
    tooltips: {
        callbacks: {
            label: function(tooltipItem, data) {
                // ... existing code references (data)
            }
        }
    }
}");

// Version 3
->optionsRaw("{
    plugins: {
        tooltip: {
            callbacks: {
                label: function(context) {
                    // ... updated code references (context.dataset.data)
                }
            }
        }
    }
}");

Step 6 - Update Title syntax

1. Headings (called title in Chartjs) are now namespaced under 'plugins' so you will need to move any titles in the Options() or OptionsRaw() declarations inside the plugins options grouping.

Step 7 - Testing

Search for Usages:

1. Search inside your Laravel application for instances where Chartjs is used and check that the charts are rendering as expected. One way to find the chart usages is to look for calls to:

app()->chartjs

Functional Testing:

2. Execute comprehensive tests on all pages and components that utilize Chartjs to ensure that the charts render correctly, and there are no runtime errors.

Error Handling:

3. Implement robust error handling mechanisms to capture any issues that may arise during the transition. Log errors and exceptions for further analysis.

Cross-Browser Testing:

4. Verify the compatibility of your charts across different browsers to ensure a consistent user experience.