Nette Documentation Preview

syntax
Composer Usage Tips
*******************

<div class=perex>

Composer is a tool for dependency management in PHP. It allows you to declare the libraries your project depends on and it will install and update them for you. We will learn:

- how to install Composer
- use it in new or existing project

</div>


Installation
============

Composer is an executable `.phar` file that you download and install as follows.


Windows
-------

Use the official installer [Composer-Setup.exe|https://getcomposer.org/Composer-Setup.exe].


Linux, macOS
------------

All you need is 4 commands, which you can copy from [this page |https://getcomposer.org/download/].

Further more, by copying into folder that is in system's `PATH`, Composer becomes globally accessible:

```shell
$ mv ./composer.phar ~/bin/composer # or /usr/local/bin/composer
```


Use in Project
==============

To start using Composer in your project, all you need is a `composer.json` file. This file describes the dependencies of your project and may contain other metadata as well. The simplest `composer.json` can look like this:

```js
{
	"require": {
		"nette/database": "^3.0"
	}
}
```

We're saying here, that our application (or library) depends on package `nette/database` (the package name consists of a vendor name and the project's name) and it wants the version that matches the `^3.0` version constraint.

So, when we have the `composer.json` file in the project root and we run:

```shell
composer update
```

Composer will download the Nette Database into directory `vendor`. It also creates a `composer.lock` file, which contains information about exactly which library versions it installed.

Composer generates a `vendor/autoload.php` file. You can simply include this file and start using the classes that those libraries provide without any extra work:

```php
require __DIR__ . '/vendor/autoload.php';

$db = new Nette\Database\Connection('sqlite::memory:');
```


Update to the Latest Version
============================

To update all used packages to the latest version according to version constraints defined in `composer.json` use command `composer update`. For example for dependency `"nette/database": "^3.0"` it will install the latest version 3.x.x, but not version 4.

To update the version constrains in the `composer.json` file to e.g. `"nette/database": "^4.1"`, to enable to install the latest version, use the `composer require nette/database` command.

To update all used Nette packages, it would be necessary to list them all on the command line, eg:

```shell
composer require nette/application nette/forms latte/latte tracy/tracy ...
```

Which is impractical. Therefore, use a simple script "Composer Frontline":https://gist.github.com/dg/734bebf55cf28ad6a5de1156d3099bff that will do it for you:

```shell
php composer-frontline.php
```


Creating New Project
====================

New Nette project can be created by executing a simple command:

```shell
composer create-project nette/web-project name-of-the-project
```

Instead the `name-of-the-project` you should provide the name of the directory for your project and execute the command. Composer will fetch the `nette/web-project` repository from GitHub, which already contains the `composer.json` file, and right after that install the Nette Framework itself. The only thing which remains is to [check write permissions |/troubleshooting#setting-directory-permissions] on directories `temp/` and `log/` and you're ready to go.


PHP Version
===========

Composer always installs those versions of packages that are compatible with the version of PHP you are currently using. Which, of course, may not be the same version as PHP on your web host. Therefore, it is useful to add information about the PHP version on the host to the `composer.json` file, and then only versions of packages compatible with host will be installed:

```js
{
	"require": {
		...
	},
	"config": {
		"platform": {
			"php": "7.2"   # PHP version on host
		}
	}
}
```


Packagist.org - Global Repository
=================================

[Packagist |https://packagist.org] is the main package repository, in which Composer tries to search packages, if not told otherwise. You can also publish your own packages here.


What If We Don’t Want the Central Repository
--------------------------------------------

If we have internal applications or libraries in our company, which cannot be hosted publicly on Packagist, we can create our own repositories for those project.

More on repositories in [the official documentation |https://getcomposer.org/doc/05-repositories.md#repositories].


Autoloading
===========

A key feature of Composer is that it provides autoloading for all classes it installs, which you start by including a file `vendor/autoload.php`.

However, it is also possible to use Composer to load other classes outside the folder `vendor`. The first option is to let Composer scan the defined folders and subfolders, find all the classes and include them in the autoloader. To do this, set `autoload > classmap` in `composer.json`:

```js
{
	"autoload": {
		"classmap": [
			"src/",      #  includes the src/ folder and its subfolders
		]
	}
}
```

Subsequently, it is necessary to run the command `composer dumpautoload` with each change and let the autoloading tables regenerate. This is extremely inconvenient, and it is far better to entrust this task to [RobotLoader|/robot-loader], which performs the same activity automatically in the background and much faster.

The second option is to follow [PSR-4 |https://www.php-fig.org/psr/psr-4/]. Simply saying, it is a system where the namespaces and class names correspond to the directory structure and file names, ie `App\Router\RouterFactory` is located in the file `/path/to/App/Router/RouterFactory.php`. Configuration example:

```js
{
	"autoload": {
		"psr-4": {
			"App\\": "app/"   # the App\ namespace is in the app/ directory
		}
	}
}
```

See [Composer Documentation |https://getcomposer.org/doc/04-schema.md#psr-4] for exactly how to configure this behavior.


Calling Commands
================

You can call your own custom commands and scripts through Composer as if they were native Composer commands. Scripts located in the `vendor/bin` folder do not need to specify this folder.

As an example, we define a script in the `composer.json` file that uses [Nette Tester |tester:] to run tests:

```js
{
	"scripts": {
		"tester": "tester tests -s"
	}
}
```

We then run the tests with `composer tester`. We can call the command even if we are not in the root folder of the project, but in a subdirectory.


Send Thanks
===========

We will show you a trick that will make open source authors happy. You can easily give a star on GitHub to the libraries that your project uses. Just install the `symfony/thanks` library:

```shell
composer global require symfony/thanks
```

And then run:

```shell
composer thanks
```

Try it!


Configuration
=============

Composer is closely integrated with version control tool [Git |https://git-scm.com]. If you do not use Git, it is necessary to tell it to Composer:

```shell
composer -g config preferred-install dist
```

{{sitename: Best Practices}}

Composer Usage Tips

Composer is a tool for dependency management in PHP. It allows you to declare the libraries your project depends on and it will install and update them for you. We will learn:

  • how to install Composer
  • use it in new or existing project

Installation

Composer is an executable .phar file that you download and install as follows.

Windows

Use the official installer Composer-Setup.exe.

Linux, macOS

All you need is 4 commands, which you can copy from this page.

Further more, by copying into folder that is in system's PATH, Composer becomes globally accessible:

$ mv ./composer.phar ~/bin/composer # or /usr/local/bin/composer

Use in Project

To start using Composer in your project, all you need is a composer.json file. This file describes the dependencies of your project and may contain other metadata as well. The simplest composer.json can look like this:

{
	"require": {
		"nette/database": "^3.0"
	}
}

We're saying here, that our application (or library) depends on package nette/database (the package name consists of a vendor name and the project's name) and it wants the version that matches the ^3.0 version constraint.

So, when we have the composer.json file in the project root and we run:

composer update

Composer will download the Nette Database into directory vendor. It also creates a composer.lock file, which contains information about exactly which library versions it installed.

Composer generates a vendor/autoload.php file. You can simply include this file and start using the classes that those libraries provide without any extra work:

require __DIR__ . '/vendor/autoload.php';

$db = new Nette\Database\Connection('sqlite::memory:');

Update to the Latest Version

To update all used packages to the latest version according to version constraints defined in composer.json use command composer update. For example for dependency "nette/database": "^3.0" it will install the latest version 3.x.x, but not version 4.

To update the version constrains in the composer.json file to e.g. "nette/database": "^4.1", to enable to install the latest version, use the composer require nette/database command.

To update all used Nette packages, it would be necessary to list them all on the command line, eg:

composer require nette/application nette/forms latte/latte tracy/tracy ...

Which is impractical. Therefore, use a simple script Composer Frontline that will do it for you:

php composer-frontline.php

Creating New Project

New Nette project can be created by executing a simple command:

composer create-project nette/web-project name-of-the-project

Instead the name-of-the-project you should provide the name of the directory for your project and execute the command. Composer will fetch the nette/web-project repository from GitHub, which already contains the composer.json file, and right after that install the Nette Framework itself. The only thing which remains is to check write permissions on directories temp/ and log/ and you're ready to go.

PHP Version

Composer always installs those versions of packages that are compatible with the version of PHP you are currently using. Which, of course, may not be the same version as PHP on your web host. Therefore, it is useful to add information about the PHP version on the host to the composer.json file, and then only versions of packages compatible with host will be installed:

{
	"require": {
		...
	},
	"config": {
		"platform": {
			"php": "7.2"   # PHP version on host
		}
	}
}

Packagist.org – Global Repository

Packagist is the main package repository, in which Composer tries to search packages, if not told otherwise. You can also publish your own packages here.

What If We Don’t Want the Central Repository

If we have internal applications or libraries in our company, which cannot be hosted publicly on Packagist, we can create our own repositories for those project.

More on repositories in the official documentation.

Autoloading

A key feature of Composer is that it provides autoloading for all classes it installs, which you start by including a file vendor/autoload.php.

However, it is also possible to use Composer to load other classes outside the folder vendor. The first option is to let Composer scan the defined folders and subfolders, find all the classes and include them in the autoloader. To do this, set autoload > classmap in composer.json:

{
	"autoload": {
		"classmap": [
			"src/",      #  includes the src/ folder and its subfolders
		]
	}
}

Subsequently, it is necessary to run the command composer dumpautoload with each change and let the autoloading tables regenerate. This is extremely inconvenient, and it is far better to entrust this task to RobotLoader, which performs the same activity automatically in the background and much faster.

The second option is to follow PSR-4. Simply saying, it is a system where the namespaces and class names correspond to the directory structure and file names, ie App\Router\RouterFactory is located in the file /path/to/App/Router/RouterFactory.php. Configuration example:

{
	"autoload": {
		"psr-4": {
			"App\\": "app/"   # the App\ namespace is in the app/ directory
		}
	}
}

See Composer Documentation for exactly how to configure this behavior.

Calling Commands

You can call your own custom commands and scripts through Composer as if they were native Composer commands. Scripts located in the vendor/bin folder do not need to specify this folder.

As an example, we define a script in the composer.json file that uses Nette Tester to run tests:

{
	"scripts": {
		"tester": "tester tests -s"
	}
}

We then run the tests with composer tester. We can call the command even if we are not in the root folder of the project, but in a subdirectory.

Send Thanks

We will show you a trick that will make open source authors happy. You can easily give a star on GitHub to the libraries that your project uses. Just install the symfony/thanks library:

composer global require symfony/thanks

And then run:

composer thanks

Try it!

Configuration

Composer is closely integrated with version control tool Git. If you do not use Git, it is necessary to tell it to Composer:

composer -g config preferred-install dist