---
title: Setup the Project | Shopware Community Hub
description: >-
This section is a short step-by-step guide on setting up your project and the
tools to use.
canonical_url: 'https://hub.shopware.com/learn/unit/setup-project'
---
# Setup the Project
- Learn about how to **setup a new project**.
- Understand about which **code editor** to choose, and about **version controller**.
- Learn about **maintaining** the repository.
# Project Setup
Great! Now that you have a Shopware instance ready, let's focus on setting up your local project with version control and an IDE (Integrated Development Environment). This setup will help you manage your code efficiently and streamline your development process.
## Organizing your Shopware project for version control
### IDE Setup
Your IDE will be your primary tool for writing and debugging code, so it's essential to set it up correctly.
For the best use, it's recommended that you work in PhpStorm. However, you can also work in VS Code or a similar IDE.
#### PhpStorm Setup
[PhpStorm](https://www.jetbrains.com/phpstorm/download/#section=mac) is a popular IDE for PHP development. It has excellent support for Shopware.
1. **Open Project**: Start by opening your Shopware project in PhpStorm.
2. **Configure PHP Interpreter**:
- Go to `File > Settings > PHP` (or `PhpStorm > Preferences > PHP` on macOS).
- Add a new local interpreter.
- Point it to the location of your locally installed PHP executable (e.g., C:\xampp\php\php.exe on Windows or /usr/bin/php on Linux/Mac).
3. **Xdebug**
Xdebug is a PHP extension with powerful debugging, error handling, and profiling capabilities.
3.1 **Enable Xdebug**
- Under "Debug," enable Xdebug in the same PHP settings window.
- Ensure your `docker-compose.yml` file has Xdebug configured.
Xdebug can consume a lot of resources while enabled and can slow down your system. Only enable it when you're actively debugging.
4. **Configure Code Style**:
- Shopware follows [PER 2.0](https://www.php-fig.org/per/coding-style/) coding standards.
- Go to `File > Settings > Editor > Code Style > PHP` and ensure the settings align with PSR-12.
5. **Set Up Shopware Plugin Development**:
- Use the "Symfony" plugin in PhpStorm to recognize the Symfony framework components used by Shopware.
- Configure the plugin path if you're developing custom plugins.
6. **Working with Git in PhpStorm**:
- PhpStorm has built-in Git support. You can manage your version control directly from the IDE, including committing, branching, merging, and pushing changes.
#### VSCode Setup
[VSCode](https://code.visualstudio.com/download) is a lighter, free alternative to PhpStorm and works well with Shopware.
1. **Open Project**: Open your Shopware project in VSCode.
2. **Install Extensions**:
- **PHP Intelephense**: For PHP autocomplete and linting.
- **PHP Debug**: For Xdebug integration.
- **Symfony Support**: For recognizing Symfony components.
- **Shopware Language Server**: Supports autocompletion, navigation, and code insights for Shopware projects.
- **EditorConfig**: Ensures consistent coding styles.
- **ESLint**: For JavaScript/TypeScript linting (useful if you're working on frontend code).
3. **Configure PHP and Xdebug**:
- Go to `File > Preferences > Settings` and search for `PHP`.
- Point the PHP executable to the one inside your Docker container.
- For Xdebug, configure a `launch.json` file for debugging:
```json
{
"version": "0.2.0",
"configurations": [
{
"name": "Listen for Xdebug",
"type": "PHP",
"request": "launch",
"port": 9003,
"pathMappings": {
"/var/www/html": "${workspaceFolder}"
}
}
]
}
```
4. **Git Integration**:
- VSCode has built-in Git support, which is accessible from the Source Control tab. You can stage changes, commit, push, pull, and manage branches directly from within the editor.
### .gitignore Setup
When working with version control, it's essential to ensure that specific files and directories aren't included in your Git repository. These are typically environment-specific files or can be generated (like compiled code or vendor dependencies).
Shopware projects should have a `.gitignore` file that includes the following:
```txt
# Ignore Composer's vendor directory
/vendor/
/composer.lock
# Ignore Shopware's cache and logs
/var/cache/
/var/log/
# Ignore node_modules for frontend dependencies
/node_modules/
/public/bundles/
/public/media/
/public/thumbnail/
/public/theme/
/config/jwt/
/config/packages/local.yaml
# Ignore the environment variables file
.env
# Ignore IDE configuration directories
.idea/
/.vscode/
# Ignore Docker and other development-related files
docker-compose.override.yml
```
## Setting Up the Repository
1. **Initialize Git**: If you haven't already done so, initialize your Git repository inside the Shopware project directory:
```bash
git init
```
2. **Initial Commit**: Add all the necessary files to your repository and commit them:
```bash
git add .
git commit -m "Initial commit of Shopware project"
```
3. **Remote Repository**: If you’re using a remote repository service like GitHub, GitLab, or Bitbucket, create a new repository there and link it to your local repository:
```bash
git remote add origin
git push -u origin master
```
## Development Workflow
With version control and your IDE set up, here's a typical development workflow:
1. **Create a New Branch**: For any new feature or bug fix, create a new Git branch:
```bash
git checkout -b feature/your-feature-name
```
Use the ticket ID to name your feature branch, ensuring it reflects a more relevant and descriptive purpose.
2. **Develop Your Feature**:
- Write code using your IDE. Use the integrated tools to check for coding standards, run tests, and debug.
3. **Commit Changes**: Regularly commit your changes with meaningful commit messages:
```bash
git add .
git commit -m "Implement feature X"
```
4. **Push Changes**: Push your branch to the remote repository:
```bash
git push origin feature/your-feature-name
```
5. **Create a Pull Request**: On your Git hosting service (GitHub, GitLab, etc.), create a pull request to merge your changes into the main branch. Review and merge after approval.
6. **Deploy**: Depending on your deployment process, you can automate deployments through CI/CD pipelines or manually deploy by merging changes to a specific branch (e.g., `production` or `main`).
## Additional Tools
- **PHPUnit** is used to test your Shopware code. Configure PHPUnit within your IDE for easy testing.
- **ESLint/Prettier** for maintaining consistent code quality in JavaScript/TypeScript files.
- **Docker-compose.override.yml**: Use this file to customize your local Docker environment without affecting the main setup, especially useful for different environments (dev, staging, prod).
By following these guidelines, you will have a well-organized, efficient development environment that leverages the power of version control and modern IDE features. This setup improves productivity and helps maintain code quality and consistency across the team.