Extension Developers; Show us your workflow!

Ralkage

Hello Flarumnites and extension developers!

I come asking a few simple (yet requires extensive explanation) questions, how does your workflow look like when you start to develop extensions for Flarum? What is your process? What does your set up look like? I want to know (and I'm sure others do too) about how you develop extensions for such a beautifully on-going crafted piece of software!

As I am known for my curiosity and drive to keep my team on track as well as getting to know my other fellow development groups out there (Flagrow I see you!). I just simply want to pick your brains about the processes you follow and the way you think on an extensive scale.

I am also doing a case study which will be required some time this year during my M.A. Degree of Software Development courses.

Share with me your wisdom and thought process!

Franz

When I started my recent extension, I used Studio (my own project as well) to require and install the extension using Composer, despite it not being available in Packagist at that time.

luceos

Set up

OSX (although I came from windows ages ago and switched to Ubuntu until a year ago).
PHPStorm with open source license (yes .. one benefit of doing that).
A regular macbook pro from last year with a memory upgrade, 13" no bar, but lots of foo ?.
Laravel Valet for serving sites, please note I have done everything else like developing on a remote server, docker, vagrant and local webservers.
Local Mariadb for database.
PHP 7.1 installed locally using brew.
The best terminal combination.
Sequel Pro for viewing the databases.
yarn installed via brew.

Now that's the software and tools. I have one flarum installation under Sites if you create that on OSX under your home directory it gets a fancy icon. That one flarum installation is a simple ~Sites$ composer create-project flarum/flarum flarum and then with a modified composer.json that points to the workbench subdirectory, every extension I work on lives there.

The workbench method is explained here. Please note that @Franz studio is based on the same method.

Some additionals based on the above

Your Operating System is important. One of the reasons to use a Linux based OS is file case sensitivity and directory separators. Okay, technical terms, this only is problematic if your code will run on computers (read webservers) that do not run Windows, which is very much likely based on the market share. Please note OSX also has to be configured to be case sensitive.

PHPStorm is an IDE. Lots of people will tell you that using an IDE is for noobs or whatever. I actually started coding on dreamweaver and then on a simple text editor called Kate. In the end you have to pick the tool that is best for you, mastering one takes a lot of time however. And tools that increase your coding efficiency always make more sense than those that do not. Important features of PHPStorm I value:

Tells me when code is wrong, also for specific versions of js or php.
Helps me go through my code easily by clicking any class.
Hints and autocompletes classes, properties and arguments.
Can do tasks I hate to do myself, Gulping, Unit testing, composer tasks (since version 2017.2), Git.
Offers plenty of plugins and themes. Having an editor that pleases you increases your chances of finding all of it enjoyable.

New extension

Every time I start a new extension this is my workflow:

Have an idea, think a lot about it before you start.
Discuss your concept with some people, get a good feeling about the goals even if they seem out of your reach.
Come up with a name, yes.. I hardly ever start on an extension and afterwards rename it. Once published renaming an extension including namespaces etc is time you could have spent elsewhere.
The decision whether to actually do work on an extension is a tough one, because the more you have the more you need to maintain. Nevertheless I sometimes start out of sheer excitement with the obvious risk of them not seeing a release (soon).
Go to your version control ui, eg GitHub or GitLab and create a project on your ❤ namespace, for me that's flagrow. Make sure it's a clean one. Copy the url provided by the empty repository page, eg; git@github.com:flagrow/foo.git.
Create a new directory inside workbench, go to your workbench and type git clone git@github.com:flagrow/foo.git which will create directory foo automatically. This let's Git know you are the proud owner of another git versioned directory and .. it adds a remote server to push changes to.
Copy files from another extension, well .. because I'm lazy ? . Whenever I add files or directories phpstorm will add it to git; it will ask you about it.
- .gitignore ignores files for git
- composer.json specifies package name, description and dependencies
- .editorconfig forces a specific indentation etc.
- license.md in case it's MIT.
- contributing.md
- js/forum/package.json and js/forum/Gulpfile.js and js/forum/yarn.lock if the forum needs frontend work, replace forum with admin if I need admin work. Inside the Gulpfile.js I need to update the namespace.
- src/Listeners/AddClientAssets.php most likely I'll need publishing js or less.
Commit all this so you don't lose progress in case your computer takes off to mars git commit -am "first" then push this to the remote git push in case it tells you to define a default push branch simply follow instructions. Check your GitHub, GitLab or whatever repository page that it receives the data.

Now depending on the type of the extension I start writing the zeroes and ones (kidding here, yes rea11y). For extensions that do a lot of backend things I mostly start from that angle and work my way towards the browser. Thus the src/ directory is very often increasing in size within a matter of hours.

I've never had that I completed backend or frontend before doing work on the other. They go hand in hand. Frontend needs additional settings or model properties and backend needs to save information into the database.

Some notes during development I can think of;

Once I work on the js directories, I go into them and run yarn which installs the node_modules.
Now in phpstorm I right click the Gulpfile.js and "show gulp tasks" it now shows the task "watch" for that directory. Once double clicked phpstorm will take care of gulp watching your js files, up until you close the project.
Regularly push changes, phpstorm asks you to add files if you want to. I allow phpstorm to do so as the .gitignore takes care of files I don't need. So a command like git commit -am "message here" is enough, the a flags tells git to add all changes (leaves out files that have not yet been added to git) and m allows you to add a commit message inline. Then push the commit(s) with git push.
Keep chrome developer console open (disable cache if open in its settings) to disable browser cache.

Once the extension is coming together nicely I reconsider every feature I wanted to push into the initial release and start dropping everything that is simply too much in terms of additional work. Pushing out releases regularly helps at working with easy to complete tasks (agile anyone?).

Releasing

Copy the readme.md from another extension and modify the information.
Create a changelog.md and add the version I am about to release.
Done? Double check that everything works (again).
Don't forget to commit the changes.
Go to packagist.org and publish your package. Set up the service in your GitHub/-Lab repository so that it sends webhooks to packagist on new tags, commits etc. It's called auto updating.
If you know a ? able to install the dev-master without being a ? ask her to do a test run.
Optionally create a gif, I use Licecap for that. Update it in your readme. I mostly upload the gif to a Flarum forum with flagrow/upload on it, because again .. lazy ?
Tag your first version, in case you want to be careful use a postfix like beta, eg 0.1.0-beta or if you expect multiple betas 0.1.0-beta.1 check the semver.org site for more. For stable use 0.1.0. Read up versioning in relation to composer if you postfix.
- Tag using git tag 0.1.0 then push the tags using git push --tags.
Go to discuss.flarum.org/t/extensions and create a thread. Copy over your readme.md (sorry guys .. lazy and it works for us ?). Post and favorite it so you get email alerts.

Continued work

Some stuff to consider after the initial release;

It's better to use branches on git for new features.
We ask for code reviews from our Flagrow fellow devs for new features. This is not only to guarantee better quality, but it also is a good way of learning new things.

So.. this is all from the top of my head. I most likely should link some things and might have left out (crucial) steps.

Feel free to ask for clarification or point out things I missed.

This is all based on my experience as team member of Flagrow, a project by Gravure.

Arkinn

luceos

That's quite possibly the best, most comprehensive workflow guide I've ever seen. ? ?

Ralkage

luceos You have no idea how long I've been waiting for a response like that and it was more than inspirational ? (I actually predicted you would go into massive explanation as I read every word with heart).

I pin your post to my permanent memory as I consider it soft-mentoring in which I actually understand and wish to follow your guidance.

You are ?

datitisev

luceos That's, as others have mentioned, the most detailed guide I've ever seen for creating Flarum extensions.

One thing I see is that you use yarn, however since npm@5, npm's speed has increased by a lot, and has led me to consider going back from using npm from yarn. Currently im using npm@5.2.0 after a few months of working with yarn. But of course, whatever you are confortable with ?

I wish I could star this post, but I'll have to conform to copying it over to the Bear app that holds notes for me when I have time. Thank you so much! ?

datitisev

Ok, now I'm going to give this a shot.

Set up

macOS Sierra
PHPStorm with student license
Macbook Pro 13" with 128GB SSD & 8GB RAM from mid-2014
PHPStorm as an IDE
Atom & Sublime as an editor
- FiraCode as the font. Contains ligatures.
- Sublime only when I want to quickly edit a file with syntax highlighting, as Atom consumes quite a bit of my RAM ?
MAMP for the MySQL database and Apache
Oh-My-ZSH with basically the best terminal combination (which I just changed to)
- FiraCode as the font as well
Sequel Pro for viewing databases
npm v5.2.0, updated with n (which updates node too)

I only have one Flarum installation, which I do all my extension developing and core contributing in.
I use the workbench method as well.

Resources

Devdocs.io - dark mode with laraval and php enabled as well as some other things
Flarum API Documentation (Community Served) - the Flarum API documentation service I provide for both JavaScript and PHP

I'm not going to add anything else because I'm basically repeating luceos at this point, besides his post goes on much greater detail. ❤

0E800

Oh man, I need to read above a few more times. Thats pro.
Great information.

My workflow pales in comparison.
I start with git cloning or using composer to install someone elses extension and use a combination of nano and notepad++ to modify files.

Pretty lame as I have access to all these expensive IDE platforms and yet nano and notepad seems to do everything I need.

ganuonglachanh

Dear All

We should stick and add luceos post to the Extension developer guideline ?

Arkinn

datitisev

You sir, come in second place! lol

Kyrne

Here is mine:

3 Dev environments:

1. Digital ocean

Ubuntu 16.04
512 MB w/ 4gb swap

2. Local XAMPP

Apache
MySQL

3. Local Nginx

My development machine:

Custom built machine
- 32gb RAM
- I7-6800K
- GeForce GTX 1070
- Windows 10
PHPStorm w/ student license
Notepad++ when PHPStorm takes to long to open (why does this happen)?
Lots and lots of Spotify music

Same resources as @datitisev

Franz

Kyrne when PHPStorm takes to long to open (why does this happen)?

You can noticeably speed up initial startup by disabling plugins that you don't need.

Ralkage

Franz I was just about to reply with a similar response lol. It used to take me 2 minutes to get PHPStorm passed the splash screen and as soon as I disabled some plugins the boot time sped up tremendously.

Kyrne

Franz That helped with loading, but I still get lots of lag when I try to create a new PHP class.

clarkwinkelmann

Alright I'll give you an overview of my workflow as well.

Setup

Hardware

Main machine (desktop):
- Some HP EliteDesk computer I won at a competition
- 8 GB ram, SSD
- Dual 24" full hd screens
Secondary machine (laptop):
- MacBookAir 13"
- 8 GB ram, SSD

Software on both machines

Ubuntu 16.04
PHPStorm
Other text editors when PHPStorm is too heavy: gedit, VSCode, Bluefish
Firefox
Apache, PHP, Mysql installed locally
Composer, Yarn

Workflow

I have a Flarum install in /var/www/flarum that I serve via Apache. This install is configured with a workbench directory where all my extensions are. I plan to change this now that I can use the PHP dev server with Flarum. I usually try to store my projects as ~/Projects/{vendor}/{package}.

When starting a new extension, I simply clone an existing extension in my workbench folder. I choose the one which has the most re-usable things for the new project. I then copy other files from other extensions until I have everything I need that already exist.

Then I do some cleanup, I delete the .git data, change the namespaces, remove content from the README, etc...

When working on a project I always have a ton of tabs open in my browser. I usually have multiple tabs for Flagrow core as it's my main source of documentation, but also many tabs for other Flagrow projects I'm copying code from.

I commit via the editor I'm using (PHPStorm or VS Code), but I usually use the command line for every other git, gulp, yarn or composer operation.

When testing something, I use a combination of Firefox Private Browsing and Chrome windows to access my app via multiple users at once. I also often launch a ton of PHP dev servers with different configurations, but this does not apply so much to Flarum.

When an extension is ready and published, I have a second local Flarum install with no workbench where I check the composer packages are working.

Oh, and music: I'm usually tuned to Radio Paradise, which is a great web radio with no ads, but I also use Spotify when I want some change (but I'm on a free account so it sucks)

I feel like I'm missing a lot of steps in there, but I already wanted to share this ?

010101

I realize this is a very old thread at this point, but I think the replies here need a pseudo-developer's setup too.

On one hand, if I can create even just a basic extension, maybe I could say I'm a "developer." Because I "developed" an extension. On the other hand, thus far I have not dedicated enough time to the craft, and I'm getting old. In life, one must decide things such as: Do I spend hours/days/weeks/months learning PHP and JavaScript better? Or, do I play music and raise my kids? 😁

Anyway, If this sounds kind of like you, then my setup notes (and explanations throughout these forums) could help you out. Less-than-part-time code fiddlers unite! 😉

P.S. I didn't set this up until about 2020. And, the only reason I set up a local dev environment for the very first time was because of Flarum. I'm keeping my eye out for free 100% cloud options since I don't use this stuff a lot. It would be better if I could do all of this in GitHub Codespaces instead, for example. Versus having to keep this stuff on my Mac up to date. It feels like virtual/cloud dev environments are the future. Maybe not. But, maybe. However, I'm waiting to see if a professional one day posts how to set up Codespaces for Flarum extension development. 🤞

Setup

Device/Operating System: MacBook Pro / OSX (At times for small updates, iPhone / iOS)
Code creation/editing: VSCodium (Open Source binaries of VS Code)
Laravel Valet (Thanks @luceos for the recommendation)
MySQL with the Mac Preference Pane installed (for easy 1-click on/off)
Sequel Ace (MySQL / MariaDB management for Mac)
PHP 8+, Yarn, and other things installed using Homebrew
Mac's default Terminal
Flarum CLI

To get this set up with zero experience I simply followed Laravel Valet's instructions. And, I also search the web to find various blog posts explaining how to do things such as setting up the database. I'm pretty sure it was easy for someone with zero experience largely thanks to Laravel Valet and thanks to how nice free software like VSCodium and Sequel Ace are. A lot of things just magically work together.

Finally, I followed @luceos's post above regarding how you put Flarum in Laravel Valet's Sites folder, and it's best to do the workbench method or something similar. I put Flarum in a folder called Flarum and so then to load Flarum I simply type flarum.test into a browser.

🦄

luceos

010101 On one hand, if I can create even just a basic extension, maybe I could say I'm a "developer."

It's not about meeting the expectations of others, it's about what you produce. Coding environment, conventions, best practices are all a foothold to produce more effectively, efficiently, qualitatively. But you produce, that's all that matters.

Thanks for sharing your set up old man 😉. I'm in my fourties and I try to learn a little something from every story shared 😘