RobotLoader: Carregamento automático de classe
**********************************************

<div class=perex>

O RobotLoader é uma ferramenta que proporciona a você o conforto do carregamento automático de classes para todo o seu aplicativo, incluindo bibliotecas de terceiros.

- Elimine todas as declarações `require`
- Somente os scripts necessários serão carregados
- Não requer convenções de nomenclatura rígidas para diretórios ou arquivos
- Extremamente rápido
- Sem atualizações manuais do cache, tudo é executado automaticamente
- Biblioteca madura, estável e amplamente utilizada

</div>

Portanto, podemos esquecer esses blocos de código conhecidos:

```php
require_once 'Utils/Page.php';
require_once 'Utils/Style.php';
require_once 'Utils/Paginator.php';
//...
```


Instalação .[#toc-installation]
-------------------------------

Você pode fazer o download do RobotLoader como um [único arquivo autônomo `RobotLoader.php` |https://github.com/nette/robot-loader/raw/standalone/src/RobotLoader/RobotLoader.php], que você inclui usando `require` no seu script, e imediatamente aproveita o carregamento automático confortável para todo o aplicativo.

```php
require '/path/to/RobotLoader.php';

$loader = new Nette\Loaders\RobotLoader;
//...
```

Se estiver criando um aplicativo usando o [Composer |best-practices:composer], poderá instalá-lo via:

```shell
composer require nette/robot-loader
```


Uso .[#toc-usage]
-----------------

Semelhante à forma como o robô do Google rastreia e indexa as páginas da Web, o [RobotLoader |api:Nette\Loaders\RobotLoader] percorre todos os scripts PHP e anota quais classes, interfaces, características e enums encontrou. Em seguida, ele armazena os resultados no cache para uso em solicitações subsequentes. Você só precisa especificar quais diretórios ele deve percorrer e onde armazenar o cache:

```php
$loader = new Nette\Loaders\RobotLoader;

// Diretórios para o RobotLoader indexar (incluindo subdiretórios)
$loader->addDirectory(__DIR__ . '/app');
$loader->addDirectory(__DIR__ . '/libs');

// Defina o armazenamento em cache para o diretório "temp".
$loader->setTempDirectory(__DIR__ . '/temp');
$loader->register(); // Ativar o RobotLoader
```

E pronto, a partir de agora, não precisamos mais usar o `require`. Fantástico!

Se o RobotLoader encontrar um nome de classe duplicado durante a indexação, ele lançará uma exceção e o notificará. O RobotLoader também atualiza automaticamente o cache quando precisa carregar uma classe desconhecida. Recomendamos desativar isso nos servidores de produção, consulte [Cache |#Caching].

Se você quiser que o RobotLoader ignore determinados diretórios, use `$loader->excludeDirectory('temp')` (pode ser chamado várias vezes ou passar vários diretórios).

Por padrão, o RobotLoader relata erros nos arquivos PHP lançando uma exceção `ParseError`. Isso pode ser suprimido usando `$loader->reportParseErrors(false)`.


Aplicativo Nette .[#toc-nette-application]
------------------------------------------

Dentro do aplicativo Nette, onde `$configurator` é usado em `Bootstrap.php`, você pode configurar o RobotLoader dessa forma:

```php
$configurator = new Nette\Bootstrap\Configurator;
//...
$configurator->setTempDirectory(__DIR__ . '/../temp');
$configurator->createRobotLoader()
	->addDirectory(__DIR__)
	->addDirectory(__DIR__ . '/../libs')
	->register();
```


Analisador de arquivos PHP .[#toc-php-files-analyzer]
-----------------------------------------------------

O RobotLoader também pode ser usado exclusivamente para localizar classes, interfaces, características e enums em arquivos PHP **sem** usar a função de carregamento automático:

```php
$loader = new Nette\Loaders\RobotLoader;
$loader->addDirectory(__DIR__ . '/app');

// Procura nos diretórios por classes/interfaces/traits/enums
$loader->rebuild();

// Retorna uma matriz de pares classe => nome do arquivo
$res = $loader->getIndexedClasses();
```

Mesmo com esse uso, você pode utilizar o cache. Isso garante que os arquivos inalterados não sejam verificados novamente:

```php
$loader = new Nette\Loaders\RobotLoader;
$loader->addDirectory(__DIR__ . '/app');

// Definir o cache para o diretório "temp".
$loader->setTempDirectory(__DIR__ . '/temp');

// Examina os diretórios usando o cache
$loader->refresh();

// Retorna uma matriz de pares classe => nome do arquivo
$res = $loader->getIndexedClasses();
```


Armazenamento em cache .[#toc-caching]
--------------------------------------

O RobotLoader é muito rápido porque usa o cache de forma inteligente.

Durante o desenvolvimento, você mal percebe que ele está sendo executado em segundo plano. Ele atualiza continuamente o cache, considerando que as classes e os arquivos podem ser criados, excluídos, renomeados, etc. E ele não verifica novamente os arquivos não alterados.

Em um servidor de produção, por outro lado, recomendamos desativar as atualizações de cache usando `$loader->setAutoRefresh(false)` (em um aplicativo Nette, isso acontece automaticamente), porque os arquivos não são alterados. Ao mesmo tempo, é necessário **limpar o cache** ao fazer o upload de uma nova versão para a hospedagem.

A verificação inicial do arquivo, quando o cache ainda não existe, pode naturalmente demorar um pouco para aplicativos maiores. O RobotLoader tem uma prevenção integrada contra a "debandada do cache":https://en.wikipedia.org/wiki/Cache_stampede.
Essa é uma situação em que um grande número de solicitações simultâneas em um servidor de produção acionaria o RobotLoader e, como o cache ainda não existe, todos eles começariam a verificar os arquivos, o que sobrecarregaria o servidor.
Felizmente, o RobotLoader funciona de tal forma que somente o primeiro thread indexa os arquivos, cria o cache, e os demais esperam e usam o cache.


PSR-4 .[#toc-psr-4]
-------------------

Atualmente, você pode usar o [Composer para carregamento automático |best-practices:composer#autoloading] enquanto adere ao PSR-4. Simplificando, é um sistema em que os namespaces e os nomes das classes correspondem à estrutura de diretórios e aos nomes de arquivos, por exemplo, `App\Core\RouterFactory` estará no arquivo `/path/to/App/Core/RouterFactory.php`.

O RobotLoader não está vinculado a nenhuma estrutura fixa, portanto, é útil em situações em que você não deseja que a estrutura de diretórios seja projetada exatamente como os namespaces do PHP ou ao desenvolver um aplicativo que historicamente não usa essas convenções. Também é possível usar os dois carregadores juntos.


{{leftbar: nette:@menu-topics}}