Extension development using composer repositories path

luceos

Please note this is a quick draft from the top of my head, because the question came up so often, please add feedback if something is amiss.

If you want to create your own extension on your Flarum installation, you'll encounter the issue that your extension is not recognized if you simply create the directory under extensions. That is because composer doesn't know about it.

A common error message you will see is:

Fatal error: Uncaught exception 'ReflectionException' with message 'Class <YourClass> does not exist' in <SomePathToContainer> ...

This tutorial will explain how to set up your development environment to allow any extensions you work on to be picked up by composer.

This tutorial assumes you have installed composer globally and that you have access to ssh to run its commands.

Terminology

root/docroot - the install path of Flarum
workbench - the directory where your extensions for developing are located
package - the package as provided on packagist, with the name being a unique identifier, for instance flarum/core and hyn/guardian.
vendor - the author of the package, which is always the first part of a package name; flarum/core, hyn/guardian

The development directory

Create a directory directly under your docroot called workbench. This is the directory we will place your extensions under.

Update composer.json

Edit the composer.json of Flarum in the docroot and add under require the following:


    "repositories": [
        {
            "type": "path",
            "url": "workbench/*/"
        }
    ],

The composer json would now look like this:

{
    "name": "flarum/flarum",
    "description": "Delightfully simple forum software.",
    "type": "project",
    "keywords": ["forum", "discussion"],
    "homepage": "http://flarum.org",
    "license": "MIT",
    "authors": [
        {
            "name": "Toby Zerner",
            "email": "toby.zerner@gmail.com"
        },
        {
            "name": "Franz Liedke",
            "email": "franz@develophp.org"
        }
    ],
    "support": {
        "issues": "https://github.com/flarum/core/issues",
        "source": "https://github.com/flarum/flarum",
        "docs": "http://flarum.org/docs"
    },
    "require": {
        "flarum/core": "^0.1.0",
        "flarum/akismet": "^0.1.0",
        "flarum/approval": "^0.1.0",
        "flarum/auth-facebook": "^0.1.0",
        "flarum/auth-github": "^0.1.0",
        "flarum/auth-twitter": "^0.1.0",
        "flarum/bbcode": "^0.1.0",
        "flarum/emoji": "^0.1.0",
        "flarum/english": "^0.1.0",
        "flarum/flags": "^0.1.0",
        "flarum/likes": "^0.1.0",
        "flarum/lock": "^0.1.0",
        "flarum/markdown": "^0.1.0",
        "flarum/mentions": "^0.1.0",
        "flarum/pusher": "^0.1.0",
        "flarum/sticky": "^0.1.0",
        "flarum/subscriptions": "^0.1.0",
        "flarum/suspend": "^0.1.0",
        "flarum/tags": "^0.1.0"
    },
    "repositories": [
        {
            "type": "path",
            "url": "workbench/*/"
        }
    ],
    "require-dev": {
        "franzl/studio": "0.10.x@dev"
    },
    "config": {
        "preferred-install": "dist"
    },
    "minimum-stability": "beta"
}

Adding/creating your extension to the workbench

Existing extension

In case you already have an extension in git (github). Just go to the workbench directory with ssh and run the command to create a clone of your code:

git clone <repository>

This will automatically create a directory under workbench with the name of your repository (without the vendor name). Remember the package name in your composer.json file.

New extension

Create a new directory under workbench, make sure it follows all guidelines for an extension. Especially the composer.json file is now important for the repository-path method to work, the name specifies your package name, remember this!

Register the package in your Flarum

Now once again edit the composer.json in the docroot. If your package name is not mentioned under require, add it. The value should be *@dev. Now with ssh run composer update and you should see that your package is now symlinked from the workbench directory.

Issues

If you already had your package in the composer.json and an entry exists in the vendor folder for your package, make sure you delete that vendor subfolder before running composer update in the last step.

zethon

luceos Register the package in your Flarum

Now once again edit the composer.json in the docroot. If your package name is not mentioned under require, add it. The value should be *@dev. Now with ssh run composer update and you should see that your package is now symlinked from the workbench directory.

Where it says "The value should be *@dev", what value exactly? Composer is not able to find a simple "Hello World" app, and I suspect it's probably because I don't know what value should be *@dev.

Pherinos

luceos make sure it follows all guidelines for an extension

This page does not exists any more... 🙁

Dakoom

Great tutorial, luceos! Thank you!

Hanccc

That's really helpful!

sanjays

hi
on "composer update" its deleting my local repository

luceos

sanjays its deleting my local repository

Are you referring to the vendor or extension folder? Please be more specific.

sanjays

luceos extension

extension folder

sanjays

@luceos
I am also getting same error as
'ReflectionException' with message 'Class Cit\Tracker\Listeners\AddFootPrintJs does not exist'
i follow the given guideline for extension develop till hello world , its work fine

I tried to build stand ways as mention by flagrow with same directory structure

extensions
cit-tracker
assets
js
cittracker.js
src

Listeners
AddFootPrintJs.php

    bootstrap.php       
    composer.json

I have also added

require
"cit/cit-tracker": "*@dev" in root composer.json

"repositories": [
        {
            "type": "path",
            "url": "extensions/cit-tracker/"
        }
    ],

i also keep namespace as same for
namespace Cit\Tracker =>> boostrap.php ,
namespace Cit\Tracker\Listeners ==> AddFootPrintJs.php

But after composer update its removed the directory
please correct me if i am wrong some where
thanks for quick reply

sanjays

This is the
composer.json

{
    "name": "cit/cit-tracker",
    "description": "Configure Tracker!",
    "type": "flarum-extension",
    "require": {
        "flarum/core": "^0.1.0-beta.3"
    },
    "extra": {
        "flarum-extension": {
            "title": "CIT Tracker",
            "icon": {
                "name": "line-chart",
                "backgroundColor": "#01a6cb",
                "color": "#ffffff"
            }
        }
    },
    "autoload": {
        "psr-4": {
            "Cit\\Tracker\\": "src/"
        }
    }
}

luceos

Your repository should be in another directory, not in extensions. A symlink will be added by composer pointing from the directory set in the "path" "url" value to the extensions directory.

The directory structure in the base of your Flarum installation:

extensions
vendor
workbench
- cit-tracker
- composer.json

Now add in the composer.json of Flarum:

"repositories": [
        {
            "type": "path",
            "url": "workbench/*/"
        }
    ],

The rest looks ok. If pointing composer with the path directive to your extensions directory it will remove that directory if you already had your extension in there before.

sanjays

luceos hey thanks its work

franklingu

luceos what is the content in the composer.json inside workbench? you do not need that right? just need composer.json under my real package, in sanjays' case: inside cti-tracker?

jordanjay29

franklingu Correct, you need only create a "workbench" (name it as you please) type folder in the root directory of your flarum install, and then point to it in your flarum's composer.json as the tutorial indicates. Everything else is handled for you.

luceos

The "root" (flarum) composer holds the repositories - path reference to workbench/*/*. Inside your workbench you will create a directory with a unique name (don't use vendor/package). Inside the extension directory you do need to have a composer to help identify the package name to the root composer file.

So:

/composer.json - repositories[path] configured
/workbench/my-awesome-package/ -- your package git repository
/workbench/my-awesome-package/composer.json - [name=franklingu/some-extension]

Composer scans all workbench directories then and simply identifies whether a package with that name exists there.

SteveAzz

@luceos What is the equvilant of flarum/composer-installer it seems like that package got removed?

luceos

SteveAzz it's no longer in use, simply remove it from your composer file. It was dropped in b4 or 5 I think.

SteveAzz

So how do I mange to create the symlink? It keeps failing and just copying the file.

wuethrich

If you develop on windows you should use an absolute path to the workbench. Otherwise the extension doesn't get discovered.

    "repositories": [
        {
            "type": "path",
            "url": "C:/xampp/htdocs/flarum/workbench/*"
        }
    ],

c_costel

Thanks for this awesome post! I think your instructions should be added to the documentation. I really had no idea how to start off. Cheers!

iamdonli

Thanks for the explanation. I feel this should be added to the official tutorial too.

In case you don't want to run composer update, you can just run composer require yourExtName:*@dev to just add the extension.

zethon

Figures I figured it out immediately after posting the question.

For anyone else wondering, it was a change in my root composer.json file:

    "flarum/flarum-ext-subscriptions": "^0.1.0",
    "flarum/flarum-ext-suspend": "^0.1.0",
    "flarum/flarum-ext-tags": "^0.1.0",
    "acme/flarum-hello-world": "*@dev"    
},
"repositories": [

I originally had "acme/flarum-hello-world": "^0.1.0".