DEV Community: Kevin Wenger

Drupal 8 — Differences between Configuration API & State API

Kevin Wenger — Fri, 26 Jun 2020 07:02:59 +0000

Before getting into the main subject, be aware that this article has been first write for the Blog of Antistatique — Web Agency in Lausanne, Switzerland. A place where I work as Full Stack Web Developer.

Feel free to read it here or check it out there: https://antistatique.net/en/we/blog/2016/06/14/drupal-8-differences-between-configuration-api-state-api

Retrieve all the code on my Gist: https://gist.github.com/Sudei/822510d2a069331a4bbe84ef55570705

Happy reading.

The other day, I faced a serious problem. On importing the configuration on my production environment. all the configurations files saved for my module were overridden by the configuration on my development environments.

What I did was very simple to understand:

The customer change his configuration on the website, such as API Key of Campaign Monitor,
I create a new feature, push it on production and I use the drush cex command to export all the configuration on development env,
I use the drush cim command to import the configuration on my production env,
The web site contain now the configuration of my development environments because every configuration is exported/imported on the Configuration API.

A solution could be to use the same configuration on the production & development environments.
But it’s not possible in our case, we should sync the local database with the production one — it’s against productivity.

I took the problem upside.

On my old days with Drupal 7 I used to use:

$data = variable_set(‘test.content_types’. ‘value’);

and port this to Drupal 8 using:

\Drupal::config(‘test’)->set(‘content_types’, ‘value’);

That’s fine and it works but later when I run a drush config-import drush cim on my production server, it erase (reset) the specific configuration of my production server.

Configuration is a place to store information that you want to synchronize from development to production. This information is often created during site building and is not typically generated by regular users during normal site operation.

You should use the State API, not Configuration API, for storing local variables that shouldn’t travel between instances.

Typical usage of State API

Get a value:

$val = \Drupal::state()->get('key');

Get multiple key/value pairs:

$pairs = \Drupal::state()->getMultiple($keys);

Set a value:

\Drupal::state()->set('key','value');

Set multiple values:

\Drupal::state()->setMultiple($keyvalues);

Delete a value:

\Drupal::state()->delete('key');

Typical usage of Configuration API

Retrieve configuration as readonly:

$config = \Drupal::config('mymodule.foo');

Get a value:

$val = $config->get('key');

The configuration object that was obtained and used in the previous examples does not allow you to change configuration. If you want to change configuration, you will instead need to get the configuration object by making a call to getEditable() on the configuration factory:

$config =\Drupal::service('config.factory')->getEditable('mymodule.foo');

Set a value:

$config->set('enabled', 1);
// Save the configuration
$config->save();

Delete a value:

$config->clear('bar.boo')->save();

The State API provides a place for developers to store information about the system's state.

State information differs from configuration in the following ways:

It is specific to an individual environment.
You will never deploy to deploy it between environments.
You can reset a system, losing all state. Its configuration remains.

We try out a lot of other solution wihtout success:

Using the flags --skip-module or --partial of drush cim
Hooking the Event like ConfigEvents::DELETE and the $event->stopPropagation();

Currently it is the most elegant solution we found to solve our problem.
However, opinions differ greatly within the community about this use case of State API.

And you what do you think ?

What is next ?

More information about:

How to create a custom Autocomplete using the Drupal 8 Form API

Kevin Wenger — Fri, 26 Jun 2020 07:02:49 +0000

In this article, I will not explain how to customise/alter an Autocomplete Field Widget - which should only be used on from using the Drupal Admin UI.

Here I will try to expose you a step by step guide which explains how you can create a custom Autocomplete field using the Drupal 8 Form API Core feature - An autocomplete that you could use in your own Drupal frontend applications.

This is what you will be able to achieve at the end of this story

If you are looking for resources which explains how to implement Views to alter an Autocomplete Field, please refer to this excellent guide.

Truth can only be found in one place: the code

Robert C. Martin, Clean Code: A Handbook of Agile Software Craftsmanship

Step 1- The autocomplete form element

The other day, I was asked to create a custom Autocomplete for a project which uses a custom Form build using the Drupal 8 Form API.

At first sight, you may be interested to use the #entity_autocomplete field type - it seems exactly what you need.
Unfortunately, this is not. Indeed, the #entity_autocomplete doesn't allow you any customisation.

So, you will need the old folk's #textfield and his cousin attribute #autocomplete_route_name

The #autocomplete_route_name attribute will allow you to define a route to handle the autocomplete business logic (data you will return given the user input).

You also may add the #autocomplete_route_parameters attribute, this one gives you the possibility to send a fixed unalterable parameter to your #autocomplete_route_name, you may use it to fix the number of results to return.

Step 2 - Define autocomplete route

Now you know how to create the autocomplete form, but you will need a route to manage the logic which will fetch data & return them.
How? By simply adding the reference to the route — where data will get retrieved from — to your my_module.routing.yml file:

Be careful to use the same route name (here my_module.autocomplete.articles) in your previous #autocomplete_route_name.
Also, be sure to change permission according to your own needs.

Step 3 - Add Controller and return JSON response

Now having a routing & a form, you have to define your custom controller, with the handleAutocomplete method.
Well, it's precisely this method that makes sure that the proper data gets collected and properly formatted once requested by Drupal.

Let's dig deeper and see how we can precisely deal with specific JSON response for our textfield element.

Setup an ArticleAutoCompleteController class file under my_module/src/Controller/ArticleAutoCompleteController.php;
Then, extend the ControllerBase class and setup your handle method (in our case ::handleAutocomplete see my_module.routing.yml).

That's pretty much all the hocus-pocus that you need to have an autocomplete based on a textfield of Drupal 8.

Sources

For the most curious of you, here are some sources of additional information that inspired the creation of this article.

Purushotam Rai (24 November, 2016). Implementing #autocomplete in Drupal 8 with Custom Callbacks
See on https://www.qed42.com/blog/autocom...

Stijn Berkers (28 February, 2018). How to produce a custom auto-complete field in drupal 8
See on https://lucius.digital/en/blog/drupal...

Make-me-alive (4 May, 2014). Adding autocomplete for text-field
See on https://drupal.stackexchange.com/.../..

Stijn Berkers (18 July, 2018). How to add autocomplete to text fields in drupal 8: defining a custom route
See on https://www.optasy.com/blog/how-add-autocom...

Drupal 8 — How to translate the Config API

Kevin Wenger — Fri, 26 Jun 2020 07:02:39 +0000

Feel free to read it here or check it out there: https://antistatique.net/en/we/blog/2018/05/01/drupal-8-how-to-translate-the-config-api

Retrieve all the code on Gist: https://gist.github.com/WengerK/5c7f3df9aa5c27a95cd8a29b72b28a19

Happy reading.

As you probably already know, I live in Switzerland and - beside chocolate & cheese - this country has one another singularity: 4 official national languages. As result, more than 90% of our web creations need to be localized in at least 2 languages.

This peculiarity makes us experts in the creation of multilingual websites.

When creating applications using Drupal 8, there are many cases when the configuration forms containing data have to be managed by the client. The most concrete case is - for example - all the links of the social networks must be different according to the language.

I will explain here the whole process to enable configuration translation with a ConfigFormBase form.
I will go through the creation of the structure and the schema generation as well as the activation of the translation system.

Prerequisites

Every solution to every problem is simple. It's the distance between the two where the mystery lies.

— Derek Landy, Skulduggery Pleasant

If you do not know the Drupal 8 Config API system yet, check it out Drupal 8 - Differences between Configuration API & State API. You may also find more help directly on the official documentation.

This article is for experienced Drupal 8 developers.

Assets

Give me matter and I will build a world out of it.

— Immanuel Kant

Before explaining how it all works, you can download all the sample files below.

This article example is testable via the downloadable test module here.

To help you understand this article, 2 translatable configuration forms will be created in our example:

The first one is a simple form demonstrating the translation system of several types of fields:
- Text - translatable
- Select - untranslatable
- Checkbox - untranslatable
- Checkboxes - untranslatable
- Radios - untranslatable
- Textarea - translatable
- CKeditor - translatable

The second is a complex form, demonstrating the translation system via mapping and structure in sequence:
- Nested fields with multiple children - translatable
- Entity reference field - untranslatable
- Textarea with preprocess in sequence (then stored as array) - translatable

As you can notice, several fields are "untranslatable". It's not a deliberate choice, but the Core Drupal requires this, and that's normal! Fields that are not translatable are fields called "key" -> "value". It is therefore normal to be unable to translate keys since they have their own Business Logic. As for the values, they are translatable via the standard translation function exposed by the Core.

Setup default values

We have 2 files because we have 2 different configurations.

SettingsForm -> my_module.settings.yml
SettingsAdvancedForm -> my_module.settings_advanced.yml

These structure files are always found in the config/install folder of the module.
They correspond to the initialization of the configuration, ie the default values. These files are not mandatory by default in Drupal 8, but are required once we want to make our configuration translatable.

These files must be named in a very specific way, depending on the name of the corresponding configuration. You can find this name in the array of the getEditableConfigNames method of your configuration forms.

Let's see what the definition of the structure of our 2 forms looks like:

SettingsForm

SettingsAdvancedForm

Did you notice both content files correspond to what we save in database?! All the fields saved in the database must be there.
In addition, the structure of your configuration is also represented in this file.

SettingsForm

title: ''                # simple text field
select: ''               # select field
checkbox: FALSE          # boolean checkbox
checkboxes: { }          # array of checkboxes
radios: ''               # the value selected from radios
message: ''              # content of textarea
ckeditor:
  value: ''              # ckeditor content
  format: 'basic_html'   # ckeditor format

SettingsAdvancedForm

site:                   # array containing our data
  title: ''             # simple text field (nested)
  content:
    value: ''           # ckeditor content
    format: basic_html  # ckeditor format
mails: { }              # Values, formated as array, transformed from the textarea
entity_reference: ''    # entity reference field

Setup the schema

The schema is a single file, regardless of how many configurations your module depends on.
This file contains the tree structure corresponding to the previous step, but this time we don't add the default value to each key, but its type and a label.

Cheatsheet formats and types usable in a Drupal schema.yml 8.

Thanks to the schema configuration, we can declare which key is translatable and which is its Label in the interface of translation for the configuration!

Are you wondering why we need to provide a complete schema when we do not use all the keys for translation? Well the schema is not used only for translations !
For example, when you edit a configuration, the forms will use the schema to "type-cast" the data, which ensures that a field defined as a boolean in your schema is a boolean and not a string when it's manipulated.
In addition, this file is used for the automatic generation of the translation form, hence the need to add a Label to each key.

The schema must be created directly in the config/schema folder and must be named following the module name:my_module.schema.yml.

Here is what the schema file of our 2 forms looks like:

In short, the schema system, just like the structure file, is optional as long as you do not need to translate your configuration.

Activate the translation

Once you have created your structure file and schema file, you just have to declare to the translation system which forms expose the translations.

You just need to create the my_module.config_translation.yml file.

This file contains all the configuration exposed by the translation form.
Each form must define a title, the path to access the form and finally all the configuration keys that it exposes.

You can now access the forms from the menu:
Configuration > Regional and language > Configuration translation.

Add a translation tab

Now that your form is translatable, it is sometimes disconcerting to access it throught the "Configuration translation" page, hidden behind 3 levels of links. It would be much more convenient to access this page from a "Local task", exactly like the other pages and settings that Core Drupal 8 offers.

Local task - Basic Site Translation

By default, the translation system will generate a "Local task" - or a tab - for the translations of your form, but you may not see it, because to see this action you need to have at least 1 "Local task". I admit it's a little far-fetched, but here's a workaround.

Create a new "Local task" in your module using the my_module.links.task.yml file at the root of your module.
Add an entry for each configuration form exposing translations.

Sources

For the most curious, here are some sources of additional information that inspired the creation of this article.

Gábor Hojtsy (29 october 2015). Configuration translation development.
Retrieved from hojtsy.hu

Alex Tkachev (16 décembre 2014). Drupal 8 configuration management.
Retrieved from amazeelabs.com

Refactoring — an ode to code

Kevin Wenger — Wed, 24 Jun 2020 13:51:53 +0000

What is refactoring? Should you redo your whole project? How can you proceed?

This article will give you an overall explanation of refactoring in software development.
We will explore the theory and then present some examples from real life.
But, as I always say, no explanation is complete without clarifying the benefits and challenges first.

Let's get to it, shall we?

What is it?

Refactoring refers to independent techniques and steps to improve code that has already been written.

To make it short, refactoring is the art of increasing the maintainability of a piece of code.

There are two ways of constructing a software design. One way is to make it so simple that there are obviously no deficiencies. And the other way is to make it so complicated that there are no obvious deficiencies.
— C.A.R. Hoare

But don't get me wrong, having to refactor your own codebase is not bad. It doesn't make you a poor-skilled developer.
Actually, during your career you will always be refactoring code (yours or others).

The Technical debt is a complete part of the development process, as nicely stated in this article from Marc Friederich & Gilles Doge.

On a standard 101-key keyboard, there are 100 keys that increase technical debt, and only one key that reduces it.
— Josh Wulf

During a refactoring process, you might be doing a lot of changes, adding new Classes, renaming, reorganising. But remember, at the end of your journey you won't ever be altering the observable behaviour of the code.

First, refactoring is not debugging. Your code needs to be running in the first place.
Of course, during a refactoring process you may find bugs. The moment that you start dealing with them, you've stopped refactoring and started bug fixing, which is another mindset.

Second, refactoring is not about performance.

I was speaking with a young developer the other day who was trying to convince me that refactoring a codebase makes it obviously faster.

It is a very common misconception that bad code automatically leads to performance leaks. The performance of your code is not the goal of a refactoring process - nor even what you should expect out of it.

Finally, refactoring is not adding features.

When you are refactoring a part of your code, you should not change its behaviour, otherwise you are no longer refactoring.

Should you do it?

People who have been using your app will have no idea something changed behind the scenes.

You did not fix bugs, you did not make it faster, you did not add any new feature.

So, you may ask me "why should I refactor then?".

If an application that was written for a long time and remained then untouched is working as expected, if there's no conflict with any other system, if no features need to be added in the future,
then it can be the ugliest code in the world: it doesn't need to be refactored.

Well, the answer is quite simple. Well-structured code will make it so much easier to add new features and new capabilities in the future. And, it will make it easier to start analysing performance or overall improving the application.

By improving the code quality, you will also improve the overall team efficiency, certainly save a fair amount of money and make your developers happy to work on that codebase - or at least I hope so.

It's called technical debt, because it's like taking out a loan. You can accomplish more today than you normally could, but you end up paying a higher cost later.

If you face tedious difficulty getting approval on spending time for refactoring - because the benefits aren't immediately apparent - remember that you're not refactoring for your end-user, you're refactoring to get the future roadblocks out of your way.

How do we do it ?

For non-developer people, this part may be more tricky.
Fly, you fools !

Bored of reading theory? Alright - me too - let's dig into some real-life examples.

Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live.
— Martin Golding

There is no such thing as a set of rules or a specific order that anyone can just follow, but there is a set of techniques to help you refactor code. Here I will drop some of my favourites and easy ones to try to use in every project.

One more thing, if I could give you one piece of advice, and share insight on one thing it would be this one simple sentence: "Never refactor a production code that does not have unit tests".

The main reason is maybe pretty obvious, but let me say it out loud again: without unit tests, you will end up with broken functionalities that are nearly impossible to fix because you won't be able to figure out what's happening anymore.

So please, if you have to refactor something, first make sure it is covered by tests.

Conditional Guard Clauses (return early)

To keep readability in functions and methods, it's wise to return early if simple conditions apply that can be checked at the beginning of a method. Then, when it's hard to determine the normal flow of code execution, try to isolate checks.

It's better to return early, keeping indentation and brain power needed to follow the code low.

Isolate all special checks and edge cases into separate clauses and place them before the main checks. Ideally, you should have a flat list of conditionals, one after the other.

Assignments to Parameters

Sometimes, you will need to alter a given parameter value inside your own method body.
If this parameter is passed via reference, then after the parameter value is changed inside the method, this value is passed to the argument that called this method.
Very often, this occurs accidentally and leads to unfortunate effects. Even if parameters are usually passed by value (and not by reference), this coding quirk may be weird to those who are unaccustomed to it.

Use a local variable instead of altering the parameter.

Replace Array with Object

Arrays are an excellent tool for storing data and collections of a single type.
But if you use an array like post office boxes, storing the username in box 1 and the user's address in box 14, you will someday be very unhappy that you did that way.

You have an array that contains various types of data.

Replace the array with an object that will have separate keys for each element.

Plus, using Object over Array, you will be able to apply properties assertions, I would suggest everybody to take a look at the ArrayAccess implementations which is great to replace object-like Array.

Replace Magic Number with Symbolic Constant

Magic numbers or magic values are encountered in the source code but have no obvious meaning.
This "anti-pattern" makes it harder to understand the program and thus refactor the code.

Often, a simple Find & Replace won't work on those values, as the same data may be used for different purposes in different places, meaning that you will have to verify each line that uses this value.

Replace this number with a constant that has a human-readable name explaining the meaning of the number.

Consolidate Conditional Expression

When your code contains a lot of alternating operators that perform identical actions, it is not clear why the operators are split up.

The main purpose of consolidation is to extract the conditionals to separate methods for more clarity.

Consolidate all these conditionals in a single expression.

Use the language capabilities

Often, developers forget some awesome capabilities of the programming language they use.
Many of these features can save you a lot of effort. Take a look at the next examples and notice how it can be easy to achieve the same result by using the type hinting methodology.

Could be changed to a simpler method with the same capabilities

Inline Temp

Prevent usage of temporary variable when necessary. For example, when you have a temporary variable that is assigned the result of a simple expression and nothing more.

Replace the references to the variable with the expression itself.

What else ?

I would like to end with a few more quick tips on better coding:

Use a new array form [ ] instead of the old array()
Use === operator instead of == unless it is important to not check for the dataType
Use prefix is/has with functions that return boolean ex: isAdmin($user), hasPermission($permission, $user)
Organise class methods with public methods at the top
Always apply the single responsibility concept to your classes

Sources

For the most curious of you, here are some sources of additional information that inspired the creation of this article.

Sourcemaking (23 August, 2019). Refactoring
See on https://sourcemaking.com/refactoring

Refactoring Guru (23 August, 2019). Refactoring Guru
See on https://refactoring.guru/refactoring

Mohamed Aladdin (19 August, 2018). Refactor Your PHP legacy Code (real projects examples)
See on https://medium.com/hackernoon/refactor-your-php...

Josh Wulf (15 April, 2018). There is no good coding, only good refactoring
See on https://medium.com/@sitapati/there-is-no-good-...

Fionna Chan (11 October, 2018). Code Refactoring — How to Write Better Code
See on https://medium.com/@fionnachan/code-ref...

Thomas Deniffel (20 April, 2019). Brutal Refactoring)
See on https://medium.com/@tdeniffel/brutal-refactorin...

Samuel Roze (21 August, 2018). Refactoring the right way: regional, not global
See on https://medium.com/@sroze/refactoring-the...

Omar El Gabry (02 October, 2017). Refactoring — The Hygienic Habit
See on https://hackernoon.com/refactori...

Shawn McGrath (22 August, 2016). The Exceptional Beauty of Doom 3's Source Code
See on https://kotaku.com/the-except...

The copyright for CommitStrip is held by CommitStrip and is licensed to CommitStrip.

Drupal 8 parameters upcasting for REST resources

Kevin Wenger — Wed, 24 Jun 2020 13:51:20 +0000

What is parameters-upcasting? How does it work for REST resources? How can you implement it?

By reading those lines, I presume readers already know how to create a custom REST resources and may already know how to implement a custom parameters-upcasting for Routes & Controllers.

This article will give you an in-depth how-to of upcasting for Drupal 8 REST resources.

We will briefly explore the theory and when parameters-upcasting should be used.

Any fool can write code that a computer can understand. Good programmers write code that humans can understand.
- Martin Fowler

During my exploration of Drupal 8 and REST resources, I discover many articles explaining the parameters-upcasting paradigm for the Routes/Controllers system but none for the REST resource.
Let's fix this, shall we?

What is upcasting?

Sometimes your routes may contain one or more named parameters (also called a "slug" or sometimes a "path parameter").
Those variables will then be available in the Controller method by their name (here $node).

In most PHP code, the name of the variable does not matter but here it does: the name of the method argument must match the slug. Conversely, if the method argument name matches the name of the slug, the parameter will be passed in, irrespective of the order of arguments.

Then it would be awesome to have a sub-system capable of converting those parameters into an actual object according to our need into our Controller(s) or REST Resources.

This feature already exists into Drupal 8's route framework. It's called Parameters Upcasting (may also be called parameters converters).

The ParamConverter system takes care of converting those parameters to an object instance automatically.

Why should I implement parameter(s) upcasting ?

By using Parameters upcasting, you will keep logic out of the controllers/resources, that's what we call decoupling.
A powerful tool we have for making change easier and code more maintainable is decoupling. When we say two pieces of code are “decoupled”, we mean a change in one usually doesn't require a change in the other. When you change some feature, the fewer places in code you have to touch, the easier it is.

In programming the hard part isn’t solving problems, but deciding what problems to solve.
- Paul Graham

Parameter upcasting may also improve the readability and robustness of you code by encouraging Type hinting of Controller/Resources methods.

Finally, by decoupling logic, you will be able to let Drupal check and validate the provided entity for you in one single place.

Well, Drupal 8 lands with many built-in parameter converters:

Drupal\Core\ParamConver\EntityConverter : Parameter converter for upcasting entity IDs to full objects.
Drupal\Core\ParamConver\EntityRevisionParamConverter : Parameter converter for upcasting entity revision IDs to full objects.
Drupal\Core\ParamConver\MenuLinkPluginConverter: Parameter converter for upcasting menu entity ids to full objects.
Drupal\ctools\ParamConverter\TempstoreConverter: Parameter converter for pulling entities out of the tempstore. This is particularly useful when building non-wizard forms (like dialogs) that operate on data in the wizard and getting the route access properly.
Drupal\jsonapi\ParamConverter\EntityUuidConverter: Parameter converter for upcasting entity UUIDs to full objects. Be aware JSON:API maintains no PHP API since its API is the HTTP API. This class may change at any time and this will break any dependencies on it.

How can I implement upcasting for REST resources ?

There are two ways of constructing a software design: One way is to make it so simple that there are obviously no deficiencies and the other way is to make it so complicated that there are no obvious deficiencies.
— C.A.R. Hoare

First, you will need to create a custom ParameterConverter.

Parameter converters are being managed by the ParamConverterManager. To implement new parameter converters, you should implement the ParamConverterInterface interface.

As Parameter converters are services, you will need to add an entry to your example.services.yml to declare a new ParamConverter.

In contrast to standard routes, REST Resources uses Plugin annotations to specify the route URL. Therefore, if your custom ParamConverter requires specific route option(s), you will not be able to configure your parameters upcasting as usual.

Indeed, you will need to create and override the FooBarConverter::getBaseRoute() method and alter the route(s) with those specific option(s).

In this example, my named parameter is called foobar_placeholder and the first argument on the callback should be named the same as the slug name (foobar_placeholder).

Sources

For the most curious of you, here are some sources of additional information that inspired the creation of this article.

Drupal API Doc (16 April 2019). How upcasting parameters works.
Retrieved from drupal.org/docs/8/api

Drupal API Doc (16 April 2019). Parameter upcasting in routes.
Retrieved from drupal.org/docs/8/api

Drupal API Doc (17 February 2020). Using parameters in routes.
Retrieved from drupal.org/docs/8/api

Drupal API Doc (29 October 2018). Custom REST Resources.
Retrieved from drupal.org/docs/8/api

Drupal API Doc (16 April 2019). Implementing custom parameter converters.
Retrieved from drupal.org/docs/8/api

Drupal Core Issue Queue (29 Apr 2020). Make it possible to link to an entity by UUID.
Retrieved from drupal.org/project/drupal/issues

Drupal Core Issue Queue (16 April 2019). Upcast request arguments/attributes to full objects.
Retrieved from drupal.org/project/drupal/issues

MacOS — Trigger Notification Center when long running commands finishes

Kevin Wenger — Wed, 24 Jun 2020 13:23:00 +0000

Feel free to read it here or check it out there: https://antistatique.net/fr/node/343

Retrieve all the code on my Gist: https://gist.github.com/Sudei/ad0c1330966522c05f504d71d29f675b

Happy reading.

As a developer, I often run commands that take a while to finish:

git pull
composer install
npm install

Considering that I am not a very patient person, I get really bored waiting for these commands to finish, so during that time I usually switch to some other occupation such as:

Checking Twitter/Tech/Hacking websites,
Making & (sometimes) drinking coffee,
Playing T-Rex Runner - The hidden endless running game of Chrome.

15 minutes later, I finally come back to my terminal with a cold coffee and I discover that I forgot to cd in the correct folder. Repeat for another 15 minutes.

Isn't there a better way?

Work is hard. Distractions are plentiful. And time is short.

— Adam Hochschild, American author, journalist, and lecturer

Solution N°0 - The Junior Professor

Waiting by watching some Gifs right on the terminal with Gifi.
One of my favourite solutions but not enough "cool" for some people.

Solution N°1 - The Middle-Earth Paradigm

Making all tools faster and developers more patient.
That would work in a parallel universe where magic exists, maybe.

Solution N°2 - The Luminous Fish Effect

Use a short script that uses terminal-notifier & append it to each command such as

git pull repo@github.com | notify-me

That's pretty cool and do the job but ... I'm lazy and I don't want to append anything to my commands or predict if my command is a long-running command or not before even running it.

Solution N°3 - The Friendship Algorithm

What about trying another approach ? Instead of trying to detect long-running commands, we could simply send a notification when the CLI is not in the foreground.
Mmmh, sounds good but is that possible ? With iTerm & OSX 10.9+, you can do this !!

1) Create a new command named notify:

touch /usr/local/bin/notify && chmod +x /usr/local/bin/notify
vim /usr/local/bin/notify

2) Copy and paste this system script inside:

3) Add a custom function named f_notifyme and expose it to iTerm using PS1

vim ~/.zshrc

4) Copy and paste the function

5) We did it ! Finally, reload the source file of your terminal source ~/.zshrc and enjoy !

Enjoy your new notification cli system !

All images copyright of their respective owners.
Big thanks to @Antistatique for the review & @gratisography for images.