Learn with DrupalXpert

Guide through the essential steps to set up, understand, and begin Drupal development.

Start Your Journey

Follow our guide to set up your environment, master Git workflows, and use development tools to ensure high quality code.

Environment Setup

Install prerequisites, fork the base repository, and launch your local environment with step-by-step instructions.

Git Workflow Basics

Learn branch types, commit strategies, and best practices to manage your code effectively.

Development Tools

Utilize tools like Code Sniffer, PHPStan, and more to maintain code consistency and quality.

Setting Up Your Development Environment

A proper local development environment is the foundation for successful Drupal development. Follow these steps to install required software, fork the base project, and launch your site.

Prerequisites

Ensure you have the following tools installed on your machine:

Docker: Required to run containerized environments with DDEV.
- Linux (Ubuntu):
```
  

sudo apt-get update && sudo apt-get install docker-ce docker-ce-cli containerd.io
            
```
- Windows/Mac: Download Docker Desktop

DDEV: Simplifies local development by automating Docker configurations.

Linux:


  

curl -LO https://raw.githubusercontent.com/drud/ddev/master/scripts/install_ddev.sh && bash install_ddev.sh

Windows/Mac: Installation Instructions

Composer: PHP dependency manager used for installing Drupal libraries and modules.

Linux:


  

php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');" && php composer-setup.php --install-dir=/usr/local/bin --filename=composer

Windows: Download Composer

Git: Essential for version control and collaboration.
- Linux:
```
  

sudo apt-get install git
            
```
- Windows/Mac: Download Git

Forking the Base Project

To start your own project, fork the base repository from GitHub. This repository is located at: DrupalXpert base project

Create a Fork on GitHub
Visit the repository on GitHub and click the "Fork" button in the top-right corner to create your personal copy.

GitHub Forking Guide
Clone Your Fork
Clone your forked repository to your local machine. Replace YOUR-USERNAME with your GitHub username:
```
  

git clone https://github.com/YOUR-USERNAME/base.git my_project
cd my_project
        
```

Set Up the Upstream Remote

Link your fork to the original repository to easily fetch updates:


  

git remote add upstream https://github.com/DrupalXpert/base.git

Synchronize Your Fork
Regularly update your fork by fetching and merging changes from the upstream repository:
```
  

git fetch upstream
git checkout develop
git merge upstream/develop
        
```

Starting Your Local Environment

Initialize DDEV
In your project directory, start the containerized environment:
```
  

ddev start
        
```
Install Dependencies
Download all necessary PHP libraries and modules using Composer:
```
  

ddev composer install
        
```
For more help, refer to the Composer Documentation.
Install Drupal
Set up Drupal with a basic configuration and create an admin account. (Change default credentials for production.)
```
  

ddev drush site:install --account-name=admin --account-pass=admin -y
        
```
View Your Site
Launch your site in a browser using the generated local URL:
```
  

ddev launch
        
```
DDEV provides a secure HTTPS URL for testing functionalities that require a secure connection.

Git Workflow Basics

Our Git workflow is designed to promote best practices, ensure code stability, and streamline collaboration. Learn about branch types, commit strategies, and merging techniques.

Branch Types

main: The stable production branch. All code here is fully tested and ready for deployment.
develop: The primary branch for integrating new features and ongoing development.
feature/: Branches created from develop to work on new features.
release/: Branches used for final testing and preparation before production releases.
hotfix/: Branches for urgent fixes in the production environment.

Workflow Steps

Create a Feature Branch

Start by creating a new branch from develop for your feature:


  

git checkout develop
git checkout -b feature/your-feature

Commit Changes Frequently
Make small, descriptive commits with clear messages that explain your changes.
Merge Your Feature Branch
Before merging, update your develop branch and merge your changes:
```
  

git pull origin develop
git push
        
```
Open a Pull Request
Submit your branch for review via a pull request on GitHub.

Best Practices

Use clear, descriptive branch names (e.g., feature/login-system).
Keep your develop branch updated before creating new feature branches.
Commit small, logical changes with concise messages.
Frequently merge updates from develop into your feature branch to avoid conflicts.

Setup & Initialization

Configure your Git user details:


  

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

Initialize a new repository:
```
  

git init
                
```

Clone an existing repository:


  

git clone [repository-url]

Stage, Commit & Push

Check repository status:
```
  

git status
                
```

Stage your changes:


  

git add [file]

Commit with a message:


  

git commit -m "Your commit message"

Push to remote repository:


  

git push [alias] [branch-name]

Branching & Merging

List all branches:
```
  

git branch
                
```

Create a new branch:


  

git branch [branch-name]

Switch to a branch:


  

git checkout [branch-name]

Merge a branch into the current branch:


  

git merge [branch-name]

Remote Repositories

Add a remote repository:


  

git remote add [alias] [repository-url]

Fetch changes from a remote repository:


  

git fetch [alias]

Push changes to a remote repository:


  

git push [alias] [branch-name]

Pull changes from a remote repository:
```
  

git pull
                
```

Stash Changes

Save changes temporarily:
```
  

git stash
                
```

List stashes:


  

git stash list

Apply the most recent stash:
```
  

git stash pop
                
```

Additional Git Tips

Undo last commit (keep changes staged):


  

git reset --soft HEAD~1

Undo last commit (discard changes):


  

git reset --hard HEAD~1

Discard changes in a file:


  

git checkout -- [file]

View commit history:
```
  

git log
                
```

Revert a commit:


  

git revert [commit-hash]

Development Tools

To ensure code quality and streamline development, we use the following tools as part of our workflow:

Code Formatter:
Automatically fixes coding standards issues in PHP files for a consistent code style.
```
  

ddev phpcbf
        
```
Code Sniffer:
Analyzes PHP files for coding standards violations and reports issues without modifying files.
```
  

ddev phpcs
        
```
PHPStan for Static Analysis:
Performs static analysis on PHP code to detect potential errors.
```
  

ddev phpstan
        
```
Twig Code Sniffer:
Checks Twig templates to ensure they adhere to coding standards.
```
  

ddev twigcs
        
```
Configuration Export:
Exports all configuration changes to code, making site settings version controllable.
```
  

ddev cex
        
```
Configuration Import:
Imports configuration from code, ensuring your site matches the committed settings.
```
  

ddev cim
        
```
Cache Rebuild:
Clears and rebuilds caches so that all changes are reflected immediately.
```
  

ddev cr
        
```
Testing Frameworks:
Run PHPUnit (or Behat) tests to verify code reliability.
```
  

ddev exec vendor/bin/phpunit
        
```

Development Mode:

Disable caching and enable debugging to optimize development workflows.


  

ddev drush state:set system.performance css.preprocess 0
ddev drush state:set system.performance js.preprocess 0