Custom drivers

#

A Tinkerwell driver is a simple class that will be called when your project gets opened in the Tinkerwell application.

Usage

#

Here is how a basic custom driver for a Wordpress project looks like:

class MyCustomTinkerwellDriver extends WordpressTinkerwellDriver
{
    /**
     * Determine if the driver can be used with the selected project path.
     * You most likely want to check the existence of project / framework specific files.
     *
     * @param string $projectPath
     * @return bool
     */
    public function canBootstrap($projectPath)
    {
        return file_exists($projectPath . '/wp-load.php');
    }
 
    /**
     * Bootstrap the application so that any executed can access the application in your desired state.
     *
     * @param string $projectPath
     */
    public function bootstrap($projectPath)
    {
        require $projectPath . '/wp-load.php';
    }
}

The canBootstrap and bootstrap methods are the important pieces of every driver. They determine if the driver can be used for the given project path and how the application should get bootstrapped and prepared, so that the application is in the correct state when any code gets executed.

Providing variables

#

When a Tinkerwell driver gets loaded, you can tell Tinkerwell to automatically set variables with specific content, so that these variables are immediately available within the Tinkerwell application.

To define these variables, add a getAvailableVariables to your driver. This method should return an array of all variables and their values:

public function getAvailableVariables()
{
    return [
        '__blog' => get_bloginfo()
    ];
}

This method gets executed after the Tinkerwell drivers bootstrap method was called, so that you have access to any classes that got bootstrapped along with the driver.

Enabling and disabling the Collision Error Handler

#

By default, the Collision Error Handler is activated in the app's global preferences. However, if you wish to modify this setting for a specific project, you can do so by employing a custom driver.

Consider this: Tinkerwell typically disables the Collision feature for WordPress projects. This is due to the fact that WordPress projects often include numerous plugins, generating a multitude of PHP notices and warnings. These generally do not impact the site's functionality, but would be intercepted by the Collision handler.

Should you still want to activate the Collision feature for your WordPress project, you have the option to include a custom driver in your project and override the usesCollision method:

class MyCustomWordpressTinkerwellDriver extends WordpressTinkerwellDriver {
 
    /* ... */
 
    public function usesCollision()
    {
        return true;
    }
}

Driver location

#

Using a custom driver in an existing project

#

If you want to use your custom Tinkerwell driver in an existing project, create a folder called .tinkerwell in the application directory.

Then you can create a new file called MyCustomTinkerwellDriver.php. The file contains the driver class that you want to use for this project. Keep in mind that the class name must match the filename according to the PSR-4 standard.

Global custom drivers

#

Custom drivers can either be local within a project or used globally for all your projects. This makes it easier if you run multiple projects that have a tech stack that is not covered by the included driver setup. You cann add global drivers to your global Tinkerwell configuration path:

# Mac/Linux
~/.config/tinkerwell/CustomDriver.php
 
# Windows
C:\Users\YourUsername\.config\tinkerwell\CustomDriver.php

Please be aware that global drivers override local drivers. So if you have a local driver for a project and a global driver for the same framework, the global driver will be used.

If you feel like your custom driver might be useful for others, for example if you add support for a commonly used framework or PHP application, please consider sending the custom driver as a pull request to the beyondcode/tinkerwell repository so that everyone can benefit from the driver in the future.