Onboarding new coworkers with Craft CMS


This is the blogpost version of the presentation I gave at last week’s Craft CMS meetup in Ghent.


At the office, the team I’m on consists of a project manager, backend developers and frontend developers. The number of developers has grown and shrunk over the past year, from 4 to 6 back to 4 to 3 and back to 4. Each addition is someone new to the company and someone new to Craft CMS.

So we’ve had to run through the “getting started with Craft CMS” thing a bunch of time. Here’s a summary of our experiences, the resources we used and a bunch of things that aren’t specific to Craft but that can apply to any new developer joining your team.

Experience level

The first very important thing to take stock of is the level of experience (and/or formal development/CS eduction) the new team member has.

  • Is it their first job out of college?
  • Have they been building React apps for the past 4 years?
  • Do they have a background in Drupal/Expression Engine/another CMS

We also have a couple of interns every year, which mostly fall into the “fresh out of college” group, but for interns we do things a bit differently, more on that later.

Before we get to Craft CMS

The first must-have dealbreaker basic skill that we need (if not require) is knowledge of git and version control. Literally every line of code we write ends up in git, and it is how a manage and deploy any of our projects so if there is 1 prerequisite, this is it.

Craft CMS

The first resource we turn to for specific Craft CMS is CraftQuest. Ryan is a great teacher and has a massive amount of content available on Craft.

So we start off new co-workers with his “The Craft mindset” course. This covers the Craft specific idioms like section types, assets, field, users, elements, matrix fields, etc. There’s also a demo site they can build along with the course, to get a feel for the CP and twig templating.

Give them something real to build

Having to come up with and idea or a subject to build a site around isn’t always easy, and it probably wouldn’t be very representative of the types of projects that the team is build.

So the next “task” we tend to give a new team member is is to build (part of) a project that the team recently completed. Something small and simple, but a real project. That means it has clear requirements, it was wireframes and a design and someone on the has actually built it already. We start them off with a fresh Craft install with nothing in it and give them a week (or 2, depending on the scope) to try and build the project.

This gives a way to feel out a couple of things, but most importantly: are they ok with asking for help when they inevitably get stuck on something.

Another important note here is that whatever they end up building is ok. This is not a test and there are no wrong answers. We’ll do code review every other day, but more the steer them in the right direction to the explain things than to point out errors.

Up next is building a project or a bigger feature along side another team-member. Their code won’t be used but it’s a good exercise to go through the entire project flow: project kickoff, wireframes, requirements, testing, client training…


We’ll repeat these last 2 steps as often as is needed. And they could take anywhere from 2 weeks to 3 months, depending and the person and their experience.

Next is of course a real client project. With that comes doing estimates, building it on time and on budget, launching it, the works.


Maintenance & support

Aside from building new projects, we also like to a roll new hires into doing support for existing projects. These could be recent projects in Craft, older projects in Craft 2 or even Expression Engine sites, custom PHP stuff, email templates, ….

Working on these projects brings along a whole new set of constraints and requirements and being able to adapt to this is very useful.


1-on-1

After the new hire is integrated into to the team and in the project rotation, it can be easy to quickly forget how new they still are, even after 4 or 6 months on the job. To keep tabs with how things are going we like to do 1-on-1 meetings:

  • With the project manager / team lead. Honestly, everyone should be doing these, not just new people.
  • With a fellow team-member, rotating which one and every 2 weeks. This is a time where they can ask questions about projects, issues, something they didn’t understand very well, something they’d like the know more about, etc… These can definitely tail off when both parties feel they aren’t needed anymore.

To summarise

All this depends on the person you have joining your team. This could take 2 weeks and they could be working on an actual client project in week 3 on the job. But it could just as well take 2 months, depending on their level of experience, with Craft, web development work in general and overal work experience.

Thoughts, remarks or want to share your own experience with this? Find me on twitter

Building a Craft CMS scaffolding package

When I posted about the Craft CMS starter repo we created at work, a couple of people were very interested in how to build something like that for themselves.

So’s have a look at how we’ve done things.

Not that this is not a step-by-step or line-by-line walkthrough but more a high-level overview with some examples. If you’re trying this out for yourself and you’re stuck on something, feel free to get in touch and I’ll try help you out 🙂

Screenshot of our custom Craft install script

(We call our starter repo our “base install” so that’s what I’ll be calling it in the post)

composer create-project

We’ll be relying on Composer’s create-project command to turn our site repository in our “base install” repository. Running the command, (eg composer create-project statikbe/craft) will clone the repository and run composer install afterwards.

That means that the repository you start from should have all the plugins, templates, etc you want to have installed when starting a new project.

For your repository to work with composer, you have to register it with Packagist. In our case, that means it’s a public Github repo.

Project config

In Craft CMS 3.1, the project config feature was added. When project config is enabled, site & plugin settings are written out to a yaml file, making it easier to share settings between environments.

In the case of our base install, we’re using project config to seed our new project with the settings/sections/fields we have in that base install. That way, we can change/fix/improve things in the CP and commit those changes, to use them in the next project.

How to install

Let’s take this step by step. composer create-project statikbe/craft path/to/folder This will:

  1. Clone the base install in the folder of our choosing
  2. Run composer install, based on the composer.json we have in our base install
  3. Run the commands we’ve specified in the post-create-project-cmd. In our case that is:
  • Copy over .env.example to .env
  • Copy over .gitignore.example to .gitignore
  • Run composer dum-autoload
  • Run ./craft setup/welcome to remind users what to do next

Then we install Craft CMS, like we would in any other project. This can be done in the browser or through the command line. We’ll use the later since that’s what we’re using already.

./craft setup

This will run through the regular Craft installer (asking you for database credentials, installing Craft, creating a user).

At the very end of this process, the install will check if you have project config enabled ('useProjectConfigFile' => true in config/general.php and if a project.yaml file is present, both are true in our case). It will then try to apply the settings from that project config file to the newly installed Craft site you just created, meaning it will install plugins, create sections, create fields, etc, making it so that our new project now has all the same settings/sections/fields/plugins as our base install.


📣 If the settings from your project config are not being applied, search Craft’s logs for can't apply existing project config: and that should tell you what went wrong.


After Craft’s install script, we added one of our own. Let’s have a look at that now.

Our custom install script

The install script we have in our repository can be run by entering ./craft statik/setup , which translates to “running actionIndex from console\controllers\SetupController in the Statik module”.

The first important thing to keep in mind is that in this part of the installation process of our new site, Craft CMS is already installed and we can leverage it where needed. Like we do by running a console command from a module.

And the second trick up our sleeve is environment variables. More on that later.

You can fellow along with our controller here as we have a look at a couple of examples of command you can do.

We could add these options and values in 1 large script, but part of making this reusable across projects (and for possibly for other people) means that we wanted to have options as to what we use where & how.

Disabling project config.

While we use project config to manage settings in our base install and we have to have it enabled there, we don’t use it in our actual projects. So in our setup script we have an option to disable it.

Step 1 is to have to config setting set to an environment variable, like so: 'useProjectConfigFile' => getenv("PROJECT_CONFIG") ?? false

Step 2 is asking the question in our setup script.

In our case, we ask if you want to disable the setting, with the default being true. You can phrase it the other way around or ask just about anything you can think of. You’ll get a boolean value in return and based on that you can proceed or do your thing. In our case that thing is setting an environment variable.

Adding placeholder images

The other example we’ll look at is the function we use to add our placeholder images:

(You can find the $this->executeShellCommand we’re using in this function in the same class right here)

The idea behind this function/question in our installer is that we want to add a set of placeholder images to our new site. As you can see in the repository, we have 4 placeholders in there. When you choose to add the placeholders, the command will:

  • Create a test folder in our /files volume
  • Copy over the placeholder files to that test folder
  • Removed the original placeholders folder
  • Run ./craft index-assets/all to re-index all assets, thereby adding the files we just copied to the CMS

These are just 2 example of questions we ask during our installation script, you can find the entire script/controller here.

Moving the different questions/functions to a service is probably cleaner and something that is on our to-do list


I hope this write-up helped out a couple of people that want to try setting up something like this 🙂. If you have any feedback or questions, feel free to tweet me, email me or ping me on the Craft Discord server.

Craft CMS - Making user name fields required

When dealing with fields on the User element in Craft, you can make the custom fields required just like you would any other custom field on an entry element. But a user also comes with a firstName and lastName field, which you can’t make required.

When building a site that relied on theses name fields a coupld of weeks ago, I decided to have try and solve this. Here’s what I came up with.


When listening for the Element::EVENT_BEFORE_SAVE event on the User::class class, we can check if we have a first & last name before saving, and mark the element as invalid .

Then we add an error to the appropriate field using ->addError(). That will make validation fail, returning the user to the add/edit user screen, with the add alert under each field.

You can add this piece of code to the init() function of a module to make it work.