In the first chapter, we took a wide-angle overview of Pimcore. Now it's time to start getting our hands dirty with some code!

In this chapter, we will learn how to set up a development environment and start developing using Pimcore. This chapter is mandatory for having a working local environment and playing with Pimcore.

This chapter is organized as follows:

• Installing Pimcore from Composer (without Docker)
• Installing Pimcore using Docker
• Exploring folder conventions

Let's start our Pimcore setup!

Writing code in Pimcore is very easy and does not require any paid tools. Despite the added value of most paid tools, we decided to use only free tools to make the content of this book available to you without any limitations.

You will require the following:

• Visual Studio Code as the Integrated Development Environment (IDE)
• A decent web browser (Chrome, Firefox, or Edge, for instance)
• Docker (optional, but strongly recommended)

If you use Docker, all the additional requirements (Apache, the necessary libraries, PHP, and so on) will be managed automatically. Moreover, using Docker removes any friction between development and the production environments, offering a virtual environment that's the same at all stages. That is why, nowadays, using Docker is the recommended approach for developing applications, an approach that we adopt in this book. And that is why we based this book's examples on this technology. For those of you who are not familiar with Docker, it is a system that can download (pull) a ready-to-go environment (container) and run it on your local PC. All the samples we will provide are wrapped in a docker-compose file (a file that lists and configures the container for you), so all you need to do is to activate the environment and Docker will download all the assets required and will start it transparently. So, even if you are not well-versed with Docker, all you need to know for the purpose of this book is the following:

• Start your environment: Inside the folder where the docker-compose.yml file is contained, run docker-compose up.
• Stop your environment: Press Ctrl+C on the terminal where Docker Compose was launched; this will stop everything.
• Interact with the Pimcore container: You can just run docker-compose exec php <command> for running a command inside the container named php (in our setup, this is the Pimcore one), or just enter the container with bash and launch whatever you want by means of docker-compose exec php bash.

For install Docker, which is available on Windows, Mac, and Linux, just navigate to the official documentation: https://docs.docker.com/get-docker/.

For manual installation

If you want to install Pimcore manually, you will have to configure your local machine (or server) and all its dependencies by hand. This is only if you're not using Docker, so if you want to use Docker, you can skip this section.

The only part of the book where we use this manual approach is in the following section, Installing Pimcore with Composer (without Docker), where we will explain how to carry out a Pimcore installation from scratch.

For a manual installation, you need to install all the dependencies manually, including Composer, Apache, MySQL, PHP, and the PHP libraries. The prerequisites may change with the arrival of new Pimcore versions and technology updates. So, instead of adding a copy of the official system requirements of Pimcore, we have instead provided a link to the official page with the exact specifications: https://pimcore.com/docs/pimcore/current/Development_Documentation/Installation_and_Upgrade/System_Requirements.html.

Note

Pimcore supports MySQL and the MariaDB database engine, which is, in fact, a fork of MySQL. In this chapter, we refer to MySQL because it is the most common option. We used the official docker-compose file based on MariaDB. To avoid confusion, please consider MySQL and MariaDB as one and the same in this chapter.

All the source code is contained in the official GitHub repository for this book, which you can find at this URL: https://github.com/PacktPublishing/Modernizing-Enterprise-CMS-using-Pimcore. In this repository, you will find a folder for each chapter. Inside each folder, there will be a Readme file with all the instructions for running the code.

For those of you who are using Docker as the environment, there are no restrictions for you regarding the operating system. For Docker compatibility and system requirements, you can check the Download section of the official Docker website.

Even though we encourage the use of Docker and the book is based on Docker containers, we should not fail to explain how to perform a vanilla installation. As you will learn after following all the steps, the process of installing Pimcore the vanilla way is basically the same as what is done internally by the Docker container. The most important difference is that using Docker, you do not have to grapple with the server, dependencies, and so on. This is because Pimcore is released through Composer, the PHP package manager. This makes the installation the same in all possible scenarios. If you are inside a Docker container, a virtual machine, or your PC, Composer is the same.

So, all you need to do to install Pimcore in your local environment is to run a few commands in the terminal after you have installed all the required dependencies mentioned in the Technical requirements section:

Note

This book uses a ready-to-use Docker container for this process. We are including this section to explain how a low-level installation of Pimcore works, but if you are interested in starting Pimcore quickly, you can skip this section and go to Installing Pimcore using Docker. Moreover, unlike Docker, using Composer in your local environment has a lot of dependencies (MySQL, Composer, and others) and needs complex PHP tuning. This is well covered by the Pimcore documentation and you can follow the official guidance for that. In this section, we will cover Pimcore's installation, assuming that you already have your environment set up and you just need to install Pimcore.

1. Create a folder in your filesystem. We assume that this folder is named my-project. There are no restrictions from Pimcore about where you can create that folder. It depends on your local settings (that is, it has to be accessible to your web server). For example, when using Apache, a common value is /var/www/html.
2. Run the following command:

   COMPOSER_MEMORY_LIMIT=-1 composer create-project Pimcore/skeleton my-project

   This command will install the Pimcore/skeleton package in the my-project folder. This will also create a new folder in your filesystem, and the final path will be /your/project/my-project. Pimcore is available in two different releases: skeleton and demo. When starting a new project, it is recommended that you use the skeleton template, but if you want to see Pimcore's features, you can install the demo package to get a website with data that is ready to test. The process will take a moment, and you will see some console output that will display its progress.

3. If you do not have one yet, you will need to create a database. To do this, type the following command in your terminal:

   mysql -u root -p -e "CREATE DATABASE project_database charset=utf8mb4;"

   You can fine-tune the preceding command by changing the host, username, and password to fit your needs, or you can use a visual tool such as MySQL Workbench. You can also change the database name. The most important thing to remember is to use the right charset, utf8mb4, to fully support Unicode encoding.

4. Edit your Apache virtual host. It needs to point to the web folders inside my-project, so your Apache file should have the document root set as follows:

   DocumentRoot /my/project/my-project/public

   Note that Pimcore needs to be installed outside of the document root. So, if you installed it inside my-project, you cannot use this folder as the document root. This, besides causing functional issues, will expose you to security issues in terms of allowing access to protected content. A complete configuration for Apache can be found here: https://pimcore.com/docs/pimcore/current/Development_Documentation/Installation_and_Upgrade/System_Setup_and_Hosting/Apache_Configuration.html.

5. Set the filesystem permissions. The Apache user (or the Nginx user, depending on which web server you are using) will need to access all the files inside the Pimcore directory and will need additional write permission for the /var and /public/var folders. In most cases, this is done by entering the following code:

   chown -R www-data .
   chmod 764 ./var
   chmod 764 ./public/var

   Here, chown makes www-data (usually the group where the user that runs the web server belongs) the group owner of the Pimcore folder, and then chmod adds write permission to the required folders.

6. Navigate to the Pimcore directory and type the following command:

   cd ./my-project

   This will bring you to the /your/project/my-project directory.

7. Launch the Pimcore installation by typing the following command:

   ./vendor/bin/Pimcore-install --MySQL-host-socket=localhost --MySQL-username=yourusename --MySQL-password=yourpassword --MySQL-database=databasename

   Here, MySQL-host-socket is the hostname of the MySQL database, MySQL-username and MySQL-password are the database credentials, and MySQL-database is the database name. This command will set up the Pimcore connection settings and will install Pimcore in the database. You will be prompted to choose the admin user for the Pimcore back office; we will choose admin\pimcore as a credential, but you can use whatever you want (although the use of simple passwords in your production environment is discouraged).

   In the following screenshot, we can see the console output that we receive after launching the installation command:

   

   Figure 2.1 – Pimcore installation and admin password prompt

8. You will be prompted to enter the username and password of the Pimcore administration user, and then you will be asked to confirm the installation.
9. The final step is to set up the maintenance job. Like many platforms, Pimcore needs to perform periodic maintenance tasks, such as log rotation and cleaning temporary or old data. Pimcore's guidelines ask us to execute this task every 5 minutes to make sure the environment is always efficient. To do this, we need to add a cron job. Type the following:

   crontab -e

10. Then, enter the following content into crontab:

    */5 * * * * /your/project/bin/console maintenance

The configuration activates the maintenance job by running the console executable, with the maintenance parameter, which invokes the standard Pimcore maintenance job.

In this section, we introduced the Pimcore installation process. These instructions are quite easy to follow, but you need to have the hosting environment already installed. Installing Apache, MySQL, and configuring the network part is standard for most developers, but some system engineering knowledge is required that not all developers have (and maybe do not want to learn). Moreover, with this setup, you may have to replicate most of your jobs each time you set up a new project.

In the next section, we will learn how things are so much easier with Docker, seeing how you can do the same as what we achieved here (and maybe more) in just two commands.

Docker is the leading solution for developing containerized applications, allowing developers to configure a virtual environment in their PC that can easily be transferred to a server and be used by the user. In fact, using Docker is the modern way to develop web applications. It accelerates the setup, reduces the friction between environments, and ensures an easy-to-use, replicable system.

Pimcore embraces Docker development and has released Docker images that are ready to be used. Moreover, it has released a docker-compose file that orchestrates all the containers needed to run Pimcore.

Using Docker, you will be able to set up and start Pimcore in minutes. Using the script provided in the GitHub repository for this book, most of the process is easy.

The first step is to clone the Pimcore repository and navigate to the 2. Setting up Pimcore Development Environment folder. You can copy the files from there and paste them into your target folder. The files are as follows:

• docker-compose.yml: This contains the definition of the container; it is quite similar to the default Pimcore file.
• install.sh: This contains the installation script, which is an automated version of the installation steps from the official guide.

Let's see these two files and how we can use them.

The docker-compose file

The docker-compose file contains many container definitions for enabling all the required components. The first one is the database component:

db:
    image: mariadb:10.4
working_dir: /application
    command: [MySQLd, --character-set-server=utf8mb4, --collation-server=utf8mb4_unicode_ci, --innodb-file-format=Barracuda, --innodb-large-prefix=1, --innodb-file-per-table=1]
    environment:
      - MYSQL_ROOT_PASSWORD=ROOT
      - MYSQL_DATABASE=pimcore
      - MYSQL_USER=pimcore
      - MYSQL_PASSWORD=pimcore

In the previous snippet, we have an instance of MariaDB tuned for Pimcore usage. Using the environment variables, we set the most important parameters of the database:

• The credentials of the root user: MYSQL_ROOT_PASSWORD
• The database name: MYSQL_DATABASE
• The credentials of the service user: MYSQL_USER and MYSQL_PASSWORD

With this configuration, we need to connect to the host database using Pimcore/Pimcore credentials.

The second container to take into account is the Pimcore container. Refer to the following code snippet from the docker-compose file:

  php:
    image: Pimcore/Pimcore:PHP7.4-apache
    volumes:
     - .:/var/www/html:cached
    ports:
     - 80:80
     - 443:443
depends_on:
     - db

The name of this container is php because Pimcore relies on a PHP image. Using volume mapping, we mount the folder where the docker-compose file is located on the Pimcore directory inside the container.

The installation file

The installation file is just a set of commands that you should run individually, but condensed into a single script. This prevents any manual errors and reduces the effort needed to set up a new environment.

The script covers the following steps:

1. The first step is the Pimcore download. To do this, we need to add the following command to the script:

   COMPOSER_MEMORY_LIMIT=-1 composer create-project Pimcore/skeleton tmp

   The problem here is with the container image settings. It is created for listening to the /var/www/html/public folder, so the Pimcore installation must be done at the /var/www/html/ level. The problem is that the Composer command will need a folder to download the files from. This will create a subfolder and necessitate a change to the default container settings. So, the most common approach is to download Pimcore in a temporary folder and then move the contents of the temporary folder to the standard Apache folder. This trick is done using the following commands:

   mv tmp/.[!.]* .
   mv tmp/* .
   rmdir tmp

2. Next, we need to fix the memory usage of PHP. Pimcore requires 512 MB for the installation process, and in most cases, the default value from PHP is not sufficient. What we will do in our script is increase the memory limit by changing the configuration files with the following commands:

   echo 'memory_limit = 512M' >>/usr/local/etc/php/conf.d/docker-php-memlimit.ini;
   service apache2 reload

3. Now we are ready to start the Pimcore installation. We will install Pimcore using the settings hardcoded into the docker-compose file. To do this, we need to add the following command to our script:

   ./vendor/bin/Pimcore-install --MySQL-host-socket=db --MySQL-username=Pimcore --MySQL-password=Pimcore --MySQL-database=Pimcore

4. Finally, we have to remember that all the commands we have launched so far have been done on behalf of the root user. So, all the files and folders created belong to the root user and group. The user running the web server will be different and will belong to the www-data group. This means that the web server cannot write or read the files, based on the chmod settings. That's why we need to reset permissions at the end of this process. The following line of code does that:

   chown -R www-data .

   This chown command adds the www-data group to the files and folders permission; this is enough to enable Pimcore to read and write files.

The final version of the script is as follows:

#!/bin/bash
#Pimcore download
COMPOSER_MEMORY_LIMIT=-1 composer create-project Pimcore/skeleton tmp
#trick for moving the files
mv tmp/.[!.]* .
mv tmp/* .
rmdirtmp
#increase the memory_limit to >= 512MB as required by Pimcore-install
echo 'memory_limit = 512M' >>/usr/local/etc/php/conf.d/Docker-php-memlimit.ini;
service apache2 reload
#run installer
./vendor/bin/Pimcore-install --MySQL-host-socket=db --MySQL-username=Pimcore --MySQL-password=Pimcore --MySQL-database=Pimcore
# fix permission
chown -R www-data .

The preceding script is contained in the source code and is called install.sh. You can just copy and paste it to your source code directory and follow the instructions in the next section.

Starting Pimcore with Docker

Now that we have understood how Pimcore using Docker works, we can use our script to start Pimcore:

1. The first step is to navigate to the folder with the Pimcore setup files; in our case, the folder is called /my/project.
2. Open the terminal here and run the following command:

   docker-compose up

   This command activates the Docker environment. Because this command isn't launched with the -d parameter (run as daemon), if you close the console, the Docker environment will shut down. This console is helpful because it shows all the logs from the containers, including the Pimcore container.

3. Then, open another terminal and run the following command:

   docker-compose exec php bash install.sh

   This command will launch the install.sh script inside the container named PHP. The script will run all the instructions needed to install Pimcore. This command is only required the first time you run the container. Its purpose is just for installation.

4. Finally, open a web browser and enter the URL http://localhost/. You will see the standard Pimcore page, as indicated in the following screenshot:
   

   Figure 2.2 – The Pimcore welcome page

5. Now we can test the credential used during the setup by visiting http://localhost/admin in the address bar. You will be redirected to the login page and you will be able to enter credentials and log in to the administrative section of Pimcore. The following screenshot shows the login page:

Figure 2.3 – The Pimcore login page

From now on, performing Step 2 will be enough to run Pimcore!

What we learned in this section was how to install Pimcore using Docker in minutes. As you saw in the Starting Pimcore with Docker section, we just ran two commands and all the processes were set. This reduces the time and effort needed from hours (installing and configuring Apache, Redis, MySQL, and so on) to minutes. Now it's clear why we decided to use Docker in this book.

In the next section, we will enter the Pimcore folder structure and we will learn about what is inside each folder.

In the previous section, we downloaded and installed Pimcore on our PC. Before starting with Pimcore development, it's important to understand how the files are structured inside the filesystem.

Let's start by exploring our filesystem. In the following screenshot, we will see the Pimcore folder expanded:

Figure 2.4 – The Pimcore folders

The Pimcore folder structure is very similar to the Symphony standard. Let's look at the first-level content:

• bin: This folder contains the executables.
• config: This folder contains the YAML configuration files.
• src: This folder contains the source code related to your project.
• var: This folder contains data saved from Pimcore, such as logs or cache data.
• vendor: This is the standard folder used by Composer to store application requirements.
• public: This is your document root.
• templates: This is the folder that contains all the template files.
• translations: This is the folder for translation files.

Let's look at these in detail, one by one.

The config folder

This contains all the YAML configuration files and settings. For example, inside /config/local/database.yml, you will find the connection settings for accessing the database. As an additional example, if you want to manage routing, override services, or tune security settings, you can go here and play with the configuration files (the config.yml file is the main configuration file and is usually split into submodules, such as routing.yml, services.yml, and security.yml).

The templates folder

This folder contains the templates. You can have one subdirectory for each bundle. Adding a file into the bundle folder will override the default template file shipped with the bundle. This override mechanism is a standard Symfony feature, and all you need to override a template file is to create a folder inside templates with the name of the bundle and then replicate the folder structure inside the bundle.

The bin folder

This folder contains the binaries. By default, it contains the console executables only, but you can add your own scripts here. The console executables form the program that we use to run maintenance jobs. Adding more jobs to Pimcore won't require you to create multiple executables; you will just need to run a command such as ./bin console <myjobname>. That is why, in most cases, this folder doesn't contain anything more than the console file.

The src folder

Inside the src folder, you will also find the Kernel.php file, which represents your application kernel. The Kernel class is the main entry point of the Symfony application configuration, and as such, is stored in the src/ directory.

The var folder

The var folder is designed to contain all the private Pimcore files and is divided into many subfolders, each one storing a different kind of file. This folder must be writable from the web server.

This folder is composed of the following subfolders:

• application-logger: Here, Pimcore saves the files from the application logger. The application logger is the system that traces events relevant to the application. Such logs are stored here and can be read from the Pimcore administrative interface.
• cache: This is the Symfony cache folder. Here you will find all the generated files.
• classes: This contains files related to classes. In fact, each class definition is stored in many files inside this folder.
• config: This contains the base settings files that are overridden and extended from the app/config structure.
• email: This stores the history of sent transactional emails.
• installer: This relates to the installer kernel. It contains cached data and other information related to the installer.
• logs: This folder contains the logs from Apache and PHP. It is related to the Docker installation.
• recyclebin: This contains the data deleted from the user.
• tmp: Used for temporary file storage, such as for creating dynamic minified JavaScript files.

The vendor folder

This folder is the standard Composer folder, so there isn't any real need to spend more time talking about it. The Pimcore core bundle is stored here just like any other package.

The public folder

This is the document root of your application, and it is exposed to the web. This folder is protected by a .htaccess file and implements some rewriting rules.

This folder is composed of the following subfolders:

• bundles: You will find a folder for each bundle; each of these subfolders has a symbolic link to the folder inside the bundle (so, /src/bundlename will be visible in /public/bundlename). This is because you can change the files inside the bundle and see the change without any copying or compilation having to take place.
• var: This contains the uploaded files: images, video files, or simple attachments.

This folder also contains the index.php file, which contains the PHP application where all requests are routed.

In this section, we learned how the folders and files of Pimcore are arranged inside the source code. This was important to cover so that you can use the source code samples without any difficulty. Now you won't be lost in Chapter 4, Creating Documents in Pimcore, when we will need this feature to start a working Pimcore's instance and view the examples shown in this book.

In this chapter, we learned how to install and start a Pimcore installation from scratch. Using Docker images, we reduced the complexity of the first installation, we made our environment independent from different operating systems, and we managed to speed up the setup time. Just by typing a few commands in the terminal, all the complex processes were done automatically. This is not only valid for a development environment, but also for production. Moreover, using a container will keep things easy if you would want to move to the cloud. Pimcore can also be installed in a regular environment by taking charge of all the dependency configurations.

In the following chapters, we will use this knowledge to run the examples provided in this book. Moreover, the installation script provided can be used as a quick start guide if you want to start a new project on your own and play in the real world with Pimcore. In the next chapter, we will discover the administration UI of Pimcore, and we will learn how to move between menu items. After this step, you will be able to navigate Pimcore's functionalities, which is fundamental for following the books' tutorials.