Craft 101 Articles

On occasion, you may find it helpful to trigger a “save” on a group of elements, without visiting each one in the control panel. Craft will do this automatically under some circumstances (like changes to a section’s Default Title Format), but there are plenty of situations in which Craft can’t infer the correct course of action (like creating a new field and populating it with a value from an existing field). Craft has a number of console commands to do just this, named after each built-in element type: resave/addresses — Addresses resave/assets — Assets resave/categories Categories resave/entries— Entries resave/tags — Tags resave/users — Users In addition, the resave/all command can be used to run each other command in series, with options common to all element types. Global sets currently cannot be resaved from the command line. Commerce Craft Commerce supplements the built-in commands with a few of its own: resave/carts — Carts (incomplete orders) resave/orders — Orders (completed carts) resave/products — Products

Craft’s system requirements are simple to satisfy in local development with tools like DDEV. When it comes time to share your project with the world, though, you’ll need to find a host that meets its requirements, or provision a VPS yourself.

Trying out new technology always brings about a mix of excitement and fear. We’ve assembled a few tools and resources here to help make your first steps with Craft CMS as comfortable and rewarding as possible. Let’s dig in! 🪴 Get to know the Craft ecosystem → 🪄 Spin up our WordPress starter project → 🗃️ Import content from an existing project →

Craft Console is our centralized Cloud project and license management platform. It also powers the Craft Plugin Store, and provides flexible tools for organizing and delegating access to your collaborators. Accounts are free, and it only takes a moment to register.

Every Craft installation gets a unique license key—even if you’re using the Solo edition. Craft sends that key along with any communications to our web services (say, to check for updates), but we typically don’t know who owns a key when it’s first created. Purchasing a Pro edition license (or any plugin license), on the other hand, immediately registers it with the Craft Console account or organization. At times, this can result in some confusion about where your licenses live—especially when a site has changed hands, or a service provider took care of purchasing licenses during development. Craft Console provides a few ways to rectify this! Scope Not all license issues can be resolved by releasing or claiming a key from your account. For instance, banners in the Craft control panel indicating that a license is invalid or belongs to a different domain cannot be remedied solely by moving it to a new Console account. This guide will only cover situations in which you suspect a license is missing from the account you expect it to be in, or you aren’t sure what account it should be tied to. Claiming a License Supposing you have a license key on-hand (from a live Craft installation, a git repository, or your own records), the first thing you should try is claiming it. From your personal Console account (or an organization), click Claim License in the main menu.

In most cases, public-facing Craft sites require a valid license. We recommend that you—the client or site owner—pay for and hold those licenses so that you always have complete, current, and accurate information about them. Organizations are our way of simplifying the license management process for clients and developers. Setting up an Organization Let’s get you started with Craft Console. Create an Account Head over to console.craftcms.com/register, and enter a username, email, and password. An activation link will be sent to the provided address, which must be clicked within 24 hours.

Welcome to Craft Console This article covers features of our centralized license management tool, Craft Console. Sign in to follow along! If this will be your first time using Craft Console, get started by creating an account. Not sure if you have an account? Request a password reset link with your email address.

While DDEV is a quick, reliable way to get started with Craft, it’s not your only option! As long as your environment meets Craft’s requirements, you’ll be able to follow along. We’ll start with the fundamentals shared by most installation methods, then discuss some tool-specific tips. Please be aware that downloading or installing Craft binds you to its license. Composer Composer is a PHP dependency manager that Craft uses internally to install and update plugins—but it can also be used to install and update Craft itself. If Composer is not available on your command line, follow the global installation instructions, or use a package manager like apt or Brew. Use the create-project command to scaffold a new site from the official starter project package, in a folder named my-craft-project: `bash composer create-project craftcms/craft my-craft-project `

Craft has a built-in setup wizard that streamlines configuration of your database connection, the creation of your first user account, and basic configuration of the default site. Composer will launch the setup wizard automatically when creating a new project, but you can start it manually from your browser or by running: `bash php craft setup ` This will walk you through three steps: Establishing a Database Connection; Creating your first User; Setting a Site name and base URL; Craft then runs the installation “migration” which is responsible for creating the required database tables or “schema” and writing out (or applying) project config data.

Normally there are several ways you can update Craft CMS, but version 3.7.39 must be updated from your terminal using composer update. 1. Make sure Composer is installed wherever you’ll be running the update. Run the which composer command, and if you don’t have it follow the instructions here to download and install it. 2. Open your Craft project’s composer.json and check your craftcms/cms requirement. It should be set to one of these: Something that begins with ^ (e.g. ^3.7.0, meaning “any version equal to or after 3.7.0, and less than 4.0.0”) Something that begins with ~ (e.g. ~3.7.0, meaning “any version equal to or after 3.7.0, and less than 3.8.0”) A specific version number (e.g. 3.7.39). If it’s a specific version number, update it to 3.7.40.1. 3. Run composer update. Once the composer update command finishes, you can commit your composer.json and composer.lock files like you normally would, running future updates using whatever method you prefer.

There may be times when you’ll need to make the same changes to multiple entries, like when you’re migrating content or establishing default values for newly-created fields. Rather than applying these changes by hand, one at a time, you might be able to take advantage of Craft’s resave console commands or writing your own content migrations. Resave Commands Craft ships with console commands you can run to do a variety of things, including a series of commands for resaving each major element type: resave/assets resave/categories resave/entries resave/matrix-blocks resave/tags resave/users

This article covers common ways a Craft installation might go wrong with suggestions to help get you back on track. 503 Unavailable You may be seeing an error page like this in your browser:

The entry editing workflow has been drastically simplified in Craft 3.7. To create a new entry, go to the Entries section in your Craft CMS control panel. Each of your sections will be listed down the side of the page. Choose the one you wish to create a new entry in, and then press New entry.

Nitro includes container commands you can use to add Docker containers to your development environment. In this article we’ll use them to add a phpMyAdmin container for managing MySQL databases. phpMyAdmin is a popular, open source MySQL GUI written in PHP. If you don’t have a favorite GUI client like TablePlus but would still like a graphical interface for managing your MySQL databases, you can add a local phpMyAdmin container to do just that. We’ll assume you’ve already installed Nitro. Adding a Container Let’s add and configure the container so we can use it. 1. Create the Container First, run nitro container new and follow the prompts. `sh $ nitro container new What image are you trying to add? phpmyadmin Which image should we use? 1. phpmyadmin 2. phpmyadmin/phpmyadmin 3. bitnami/phpmyadmin 4. nazarpc/phpmyadmin 5. jackgruber/phpmyadmin 6. rkcreation/phpmyadmin 7. silintl/phpmyadmin 8. drud/phpmyadmin 9. maxexcloo/phpmyadmin 10. sk278/phpmyadmin-armhf Enter your selection: 1 What tag should we use [latest]? … downloading docker.io/library/phpmyadmin:latest Expose port 1024 on host [Y/n]? Y Does the image contain a web-based UI [Y/n]? Y What is the name of the container [phpmyadmin]? Create a file to add environment variables [Y/n]? Y Created environment variables file at "/Users/oli/.nitro/.phpmyadmin". New container "phpmyadmin.containers.nitro" added! 🐳 Apply changes now [Y/n]? Y ... ` Nitro will update its configuration and apply the changes to create your new container. You’ll see it in Docker Desktop:

Craft CMS is a self-hosted PHP application that connects to MySQL or Postgres databases. It can run on just about everything from a basic shared server, to multi-region serverless infrastructure, to a Raspberry Pi! Requirements You can view the complete list of system requirements in the documentation. Needs Assessment Every project and audience is different, so there’s no one right way to host. Here are some important considerations for your team or client: Where is your primary audience located, geographically? → Find a host that has presence in that part of the world, and make sure they are able to satisfy applicable privacy laws. How many active users do you need to support at once? → Consider Craft control panel users and front-end registrants, as well as regular viewers! Are you hosting a monolithic, headless, or hybrid front end? → Does the server only need to generate dynamic responses for control panel users, or will it load and render everything your visitors see? What portion of your site can be cached? → Statically caching full pages is a great way to stretch your resources. What volume of content does Craft CMS need to hold? → Craft scales well with large content models, but it’s always good to have a plan for projects that are apt to grow over time. Does your traffic trickle in, or come in bursts? → Have a plan to deal with sudden popularity. How critical is availability and response time? → Hosting is always a tradeoff between performance and cost. Who is going to manage and support your hosting or infrastructure? → A dedicated dev/ops engineer can help keep your stack healthy; not all hosts’ support teams can actually assist with problems that may arise. Do you anticipate regular, active website development? → Content can change any time, but software updates and improvements need to be deployed by a developer. Abstractly, your hosting solution should balance convenience, capability, and cost. Hosting Terminology These are some common terms you’re likely to encounter. Managed Hosting — Servers are configured and maintained by the host. In the event of issues with the underlying hardware, operating system, or network issues, the host typically intervenes to patch or migrate, without input from customers. These hosts do not support Craft CMS or any other software you install—their obligations end with the HTTP server, PHP interpreter, and database. Unmanaged Hosting — Unlike managed hosting, unmanaged servers are a clean slate—often provisioned with your choice of lightweight Linux. You are responsible for installing all of Craft’s underlying requirements, like an HTTP server, PHP interpreter, and database. High Availability — An umbrella term for any number of technologies that distribute traffic among multiple web servers, often with the ability to automatically add and remove resources from the pool as necessary. This can be similar to managed hosting, but shifts some of the underlying complexity onto your organization in exchange for a more failure-tolerant website. Load balancing — A load balancer distributes traffic among multiple web servers. It’s often a part of high-availability infrastructure, providing “horizontal” scaling in addition to “vertical” scaling. Platform as a Service (PaaS) — Infrastructure tailored to a specific software. Craft Cloud is a Craft-specific PaaS, but not all PaaS options support Craft (or even PHP). Virtual Private Server (VPS) — A common type of semi-managed environment that shares hardware with other servers, but is isolated through virtualization. You typically rent a VPS that has guaranteed resources, like the number of “CPUs,” memory, disk space, etc. If a host shares resources effectively, you won’t often notice or be impacted by noisy neighbors. Dedicated Server — An entire physical machine, usually in a datacenter. If a VPS is like renting an apartment, a dedicated server is akin to owning the building—its resources are fully available to you, all the time. Despite the ownership analogy, most dedicated servers are still rented from a provider. Content Delivery Network (CDN) — A layer that sits between be an important part of how your website performs across the planet. Your web server or servers would typically live behind a CDN which transparently caches pages and content all over the world so each visitor enjoys fast speeds right from their neighborhood rather than having to wait on the full round-trip to wherever your server(s) are located. Service-Level Agreement (SLA) — A formal guarantee of uptime, durability, support coverage and response times, and so on. Hosts without an SLA can still offer great service—but having specific metrics and remedies spelled out in a contract is valuable to many organizations. Common Strategies Everyone wants their website to be fast and available. A sensible hosting strategy balances durability and scale with the financial and human resources available for management. Let’s look at a few solutions. Single VPS A single VPS can be great for smaller sites with stable traffic. It means one virtual machine hosts all the web, database, and cache components Craft needs. It’s simple, low cost, and requires a minimal amount of maintenance, so long as it’s been configured well. This simplicity can also be a liability: the server exists in one location and is a single point of failure; if it’s unreachable, your site is offline. Many small projects are hosted on a single VPS, provisioned by a developer with a service like Laravel Forge, Ploi, or ServerPilot. Those services are also easy to connect with providers like Digital Ocean, Linode, or Vultr. The original Craft-optimized virtual server host is Arcustech, with rock-solid infrastructure available in fifteen datacenters across eight regions. One key benefit of a virtual server over a dedicated server or shared hosting is that they often can be scaled “vertically” after creation—say, as a site’s audience grows. While the management experience might otherwise be very similar, dedicated servers often can’t be scaled up and down without a disruptive migration process.

Craft Commerce 5.x comes with a brand new multi-store feature to complement Craft’s native multi-site architecture. Stores are configured independently—and then attached to—one or more sites (each site having one store). Your product content is still managed per-site (so it can be localized for each audience), but some core properties like prices, dimensions, and SKUs are defined for each store, or globally. In addition to connecting each site to a store, stores support multiple currencies. When you create a store, you select a primary currency; store managers can then enable additional currencies for customers to select while shopping (and to use at checkout). Limitations Commerce is currently limited to five distinct stores and five inventory locations, but has no restrictions on the number of sites those stores are connected to. There are no limits on the number of product types, SKUs, orders, stock, revenue, customers, and so on. Start building your storefront with Commerce by checking out the documentation, or read more about its key features!

Craft 3 and 4 Specific versions of Craft can be installed by altering the version constraint for craftcms/cms in your project’s composer.json. Run composer update to resolve, lock, and install the dependencies. Keep in mind that you may also need to change plugin versions to maintain compatibility! Do not manually modify files in your project’s vendor/ directory. They will be wiped out the next time composer install or the Craft updaters is run. Craft 2 Specific versions of Craft 2 are available directly from our CDN. Version numbers can be found in the sidebar on Packagist and used in this pseudo-template to download a ZIP archive: https://download.craftcms.com/craft/{major}.{minor}/{major}.{minor}.{build}/Craft-{major}.{minor}.{build}.zip For example, the URL for version 2.6.3018, would look like this: https://download.craftcms.com/craft/2.6/2.6.3018/Craft-2.6.3018.zip Note that downloading Craft releases directly still binds you to Craft’s license agreement.

Craft’s control panel is currently translated into the following languages: Arabic Chinese (Simplified) Czech Danish Dutch English (United Kingdom) English (United States) French French (Canada) German German (Switzerland) Hebrew Hungarian Italian Japanese Korean Norwegian Bokmal Persian Polish Portuguese Russian Slovak Spanish Swedish Thai Turkish Ukrainian Contributing to Control Panel Translations If you’d like to help improve Craft’s translations, please contribute to Craft’s project on Crowdin.

By default, search terms will match any keywords that begin with the search term. In other words, the search term is treated strictly on the left and fuzzy on the right. For example, a search for “dog” would match “doggo”, but a search for “fish” would not match “catfish”. You can change this default behavior using the defaultSearchTermOptions config setting: `php 'defaultSearchTermOptions' => [ 'subLeft' => true, ], ` The subLeft key determines whether the left end of search terms should be treated as fuzzy, and it’s false by default. Changing it to true causes the full search term to be treated as fuzzy. Rather than changing the default search behavior, which will affect all search queries in Craft, you can enable it for an individual element query when you set the search param: `twig {% set results = craft.entries() .section('news') .search({ query: craft.app.request.getQuery('q'), subLeft: true, }) .all() %} `

We want developers to thrive using Craft and to ensure there’s always a way to get help. As long as your Craft Pro license is paid and active, you’re entitled to free Basic Developer Support. Priority support plans with guaranteed response times are also available. Learn more on our Support Services page. Support Scope These are examples of the support we offer with the goal of being generous, but not unlimited. We sometimes break our policy at our own discretion. Supported Best practice tips and examples while you’re learning to work with Craft. A quick take from our team to help plan your first (or tenth) plugin. Help determining whether some unexpected problem is related to Craft. Help figuring out why something’s not working as expected. Not Supported Requests for calls, direct messages, or real-time communication that blocks our team’s schedule. In-depth consulting on-site migrations, code reviews, or extensive code review or troubleshooting. (Outside of paid consulting, which you can request by writing support@craftcms.com.) De-facto development expertise; Developer Support isn’t a substitute for having your own developer or someone to handle site-specific maintenance or support. Pre-release software like alpha, beta, and RC releases that are works in progress. Limitations We don’t guarantee a response time with Basic Developer Support. We don’t guarantee a resolution. We’re not responsible for your production site or data. We don’t support third-party plugins or software. Requesting Support Please send questions from the Craft CMS Help Widget in your project’s control panel, or email support@craftcms.com. If you have a bug or issue that relates directly to Craft’s source code or documentation, please consider submitting a GitHub issue instead. If you discover a security vulnerability, please see our Security Policy. If you have a question or issue related to our community code of conduct, please get in touch via craftcms.com/contact. Additional Resources There are a number of ways to get help when we can’t offer direct support: Craft Discord is our community chat server where friendly people are helping each other out all the time. Craft CMS Stack Exchange is a great resource for written Q&A. Every plugin available at plugins.craftcms.com has a public GitHub repository where you can submit issues directly to the plugin author. (Follow the “Repository” link from that plugin’s page.) The Developer Documentation includes tutorials and API references. Our Knowledge Base covers common questions and topics. Our broad range of Craft Partners are experts available for hire. CraftQuest, our official training partner, provides free and paid tutorials on a range of topics. nystudio107 blog has some great articles on advanced topics such as optimization, module development, and best practices.

Each major version of Craft CMS and Craft Commerce comes with at least two years of active support and maintenance, following its initial release. After that, we will continue to fix critical security issues (where possible) for one additional year, before the version reaches end of life and is no longer supported. Currently-Supported Versions Major Version | Released On | Active Support Until | Security Support Until ------- | ----------- | -------------------- | ---------------------- Craft CMS 4 | 4 May 2022 | 30 Apr 2025 | 30 Apr 2026 Craft Commerce 4 | 4 May 2022 | 30 Apr 2025 | 30 Apr 2026 Craft CMS 5 | 26 Mar 2024 | 30 Apr 2027 | 30 Apr 2028 Craft Commerce 5 | 30 Apr 2024 | 30 Apr 2027 | 30 Apr 2028 End-of-Life Versions Major Version | Released On | Active Support Ended | Security Support Ended ------- | ----------- | -------------------- | ---------------------- Craft CMS 3 | 4 Apr 2018 | 30 Apr 2023 | 30 Apr 2024 Craft Commerce 3 | 28 Jan 2020 | 30 Apr 2023 | 30 Apr 2024