⬅️ Back to Documentation overview
Upgrade Guide
This upgrade guide shows you how to upgrade from v1 (any release) to v2 of this package.
Follow these steps in order.
If you encounter any issues or unclarities, please 🙏, open a GitHub issue and let me know so I can make the upgrade process smoother for the next reader.
Creating, maintaining and supporting this package is a lot of work, but I want to deliver the best quality code and support that I can. If you are using this package commercially and find it helpful, please consider sponsoring me to help me make time for maintaining this project and supporting the users.
Table of Contents
- Create or update the config file
- Update the
NovaServiceProvider
- Update your calendar data provider
- Update your custom event generators
- Namespace change for interfaces
- Do the update
1. Create or update the config file
Config file config/nova-calender.php
was optional in v1 but is required in v2, and its structure has changed to accomodate configuring multiple calendar instances.
Check if config/nova-calender.php
already exists in your project.
If it doesn’t exist yet; publish it first by running the following command.
php artisan vendor:publish --provider="Wdelfuego\NovaCalendar\ToolServiceProvider" --tag="config"
Now that you’re guaranteed to have a config file, upgrade the structure as follows:
- If it contains an entry with key
title
, change that key towindowTitle
. -
Add a key
dataProvider
and set it to the full class name of yourCalendarDataProvider
.If you don’t know where to find your
CalendarDataProvider
, it’s the class that is currently being bound toCalendarDataProviderInterface
in theregister
method of yourNovaServiceProvider
. You can move theuse
statement from yourNovaServiceProvider
to the config file and set thedataProvider
entry toCalendarDataProvider::class
. -
Finally, to accomodate multiple calendar instances, the existing top-level config now turns into a specific calendar config; wrap another array around the current contents of the config file and use a string key as a uniquely identifying calendar key, to point to this config.
If you’re not going to add more calendars,
my-calendar
will do just fine as a calendar key. The calendar key is for internal use and is never exposed to the end user. -
You should end up with a
config/nova-calendar.php
file that looks something like this:use App\Providers\CalendarDataProvider; return [ // This key `my-calendar` is the calendar key. You can use whatever. 'my-calendar' => [ 'dataProvider' => CalendarDataProvider::class, 'uri' => 'calendar/my-calendar', 'windowTitle' => 'My calendar' ] ];
Adding more calendar views to your app will be as simple as adding an entry to this file under a new calendar key and implementing its calendar data provider.
2. Update the NovaServiceProvider
-
Get rid of the binding between
CalendarDataProviderInterface
and yourCalendarDataProvider
in theregister
method of yourNovaServiceProvider
:// Delete this binding from NovaServiceProvider::register $this->app->bind(CalendarDataProviderInterface::class, function($app) { return new CalendarDataProvider(); });
-
Confirm that you are not using the
CalendarDataProviderInterface
class anywhere else in yourNovaServiceProvider
, then remove this use statement from the top of the file:use Wdelfuego\NovaCalendar\Interface\CalendarDataProviderInterface;
If you find that you are still referencing that class somewhere in the
NovaServiceProvider
, don’t remove it but update theuse
statement to:use Wdelfuego\NovaCalendar\Contracts\CalendarDataProviderInterface;
-
In the
tools
method of yourNovaServiceProvider
, where you create anew NovaCalendar
, supply the calendar key to the constructor (the key used in the config file, in this example:my-calendar
).public function tools() { return [ // Supply the calendar key to the tool constructor new NovaCalendar('my-calendar'), ]; }
-
If you are creating your own menu items in the
boot
method of yourNovaServiceProvider
, update the path that is currently either hardcoded or a call toconfig('nova-calendar.uri')
to use theNovaCalendar::pathToCalendar
helper instead, like so:// Change this: MenuItem::link(__('Calendar'), config('nova-calendar.uri', 'wdelfuego/calendar'), // Into this (supply the calendar key to the pathToCalendar helper): MenuItem::link(__('Calendar'), NovaCalendar::pathToCalendar('my-calendar')),
3. Update your calendar data provider
In your calendar data provider, perform the following changes:
- The class used to extend
Wdelfuego\NovaCalendar\DataProvider\MonthCalendar
, change it to extendWdelfuego\NovaCalendar\DataProvider\AbstractCalendarDataProvider
instead. -
Make sure the method signature of your
novaResources()
method is this:public function novaResources() : array
-
If your calendar data provider implements the
exclude()
method, rename it toexcludeResource()
. -
If your calendar data provider implements the
title()
method, rename it totitleForView
and add astring $viewSpecifier
argument:// Change this: public function title() : string
// Into this: public function titleForView(string $viewSpecifier) : string
This is an infrastructural preparation that will allow you to render different calendar titles for different views in the future. You can leave the implementation of the method unchanged, since there is currently only a month view, so the supplied
$viewSpecifier
is currently always'month'
. -
Methods
firstDayOfCalendar()
andlastDayOfCalendar()
have been removed; update any calls to them tostartOfCalendar()
andendOfCalendar()
, respectively.Search your project for the removed method names to see if you depend on them anywhere else.
-
Finally, method visibility has changed for a few methods.
Check if your calendar data provider implements any of these methods and update their visibility if it does:
customizeCalendarDay()
must now bepublic
allEvents()
must now bepublic
Other low-impact changes to the calendar data provider
These changes most probably do not affect you, but are mentioned in any case so that you can be sure:
- Method
eventDataForDate()
no longer exists. That logic has been moved to the View layer insrc/View/Month.php
. If your calendar data provider implements that method, remove it and find another way to reach what you want. Create a GitHub issue for some guidance; updates to this package to restore missing functionality will be released promptly if required. - Method
calendarWeeks()
has been renamed tocalendarData()
4. Update your custom event generators
You can skip this step if you are not using custom event generators in your project.
-
The
resourceToEvents
method of custom event generators now takes$startOfCalendar
and$endOfCalendar
arguments;// Change this: protected function resourceToEvents(NovaResource $resource) : array;
// Into this: protected function resourceToEvents(NovaResource $resource, Carbon $startOfCalendar, Carbon $endOfCalendar) : array;
Add a
use Illuminate\Support\Carbon;
statement to the file if it isn’t there yet. -
This probably doesn’t affect you, but class
Wdelfuego\NovaCalendar\EventGenerator\EventGenerator
has been renamed toWdelfuego\NovaCalendar\EventGenerator\NovaEventGenerator
; update the class name if you extend the existingEventGenerator
somewhere.
5. Namespace change for interfaces
To extend backwards compatibility to PHP7.4, the interface namespace Wdelfuego\NovaCalendar\Interface
has been renamed to Wdelfuego\NovaCalendar\Contracts
. You can do a global search and replace in your project to reflect this. It is possible and quite likely you don’t need to make any changes.
6. Do the update
That’s it, your project is now ready to update to version 2.0 :).
Update the minimal version of wdelfuego/nova-calendar
to ^2.0
in your project’s composer.json
file and run composer update
.
If everything went well, your calendar is now visible and functional running the new version. The ‘previous month’ and ‘next month’ buttons are now grouped together on the left side above the calendar. If you see that and your calendar works, the upgrade was successful.
You can now make use of new features such as adding event filters and adding more calendar views to your application.
It’s been a lot of work to finalize this release and write the documentation, such as this Upgrade Guide. If you are using this package commercially and find it helpful, please consider sponsoring me to help me make time for maintaining this project and supporting the users. Thanks and happy calendaring ;)!