Por padrão, o Composer instala todos os arquivos dentro do diretório vendor. Se você quiser instalar arquivos de recursos no diretório raiz do documento web, precisará recorrer a outra solução.

Esse pacote Asset Manager é um plugin que estende o Composer para instalar qualquer arquivo de pacote fora da pasta vendor.

Além disso, ele pode ler nomes de usuário e senhas de um arquivo de configuração, para que você não precise digitá-los toda vez que o Composer busca os pacotes em repositórios que talvez precisem de autenticação, como o PHP Classes e JS Classes.

Leia esse artigo para aprender como tirar vantagem desses recursos com esse plugin do Composer.

Tornando o Composer melhor com um plugins especiais

O Composer é um excelente ferramenta para intalar pacotes necessários para projetos PHP. Entretanto, ele não é perfeito. Sempre haverá necessidades que alguns projetos possuem, as quais não são satisfeitas pela atual versão do Composer.

Felizmente, os desenvolvedores do Composer tiveram uma ótima ideia para torná-lo extensível com plugins de terceiros. Dessa forma, o Composer pode atender às necessidades de uma variedade muito maior de projetos PHP.

Plugins para o Composer são como pacotes normais, mas eles implementam a API de plugins do Composer. Essa API permite providenciar novos recursos ao alterar o processo de instalação de pacotes de formas que sejam úteis.

Instalação de arquivos fora do diretório vendor

Uma necessidade que o atual Composer não resolve é a instalação de arquivos de assets.

Assets são arquivos necessários para aplicativos web, que serão executados no lado do cliente. Por exemplo, aplicativos web precisamr servir bibliotecas Javascript, arquivos CSS, imagens etc.

Atualmente, o Composer instala os arquivos dos pacotes dentro do diretório vendor. Entretanto, arquivos asset precisam estar instalados abaixo do atual diretório raiz do documento, para que possam ser servidos ao navegador do usuário. A raiz do documento web normalmente não fica na pasta vendor.

Se precisar instalar pacotes com arquivos JavaScript, por exemplo do repositório JSClasses do Composer, uma solução alternativa precisa ser usada para que o os arquivos JavaScript desses pacotes sejam instalados nos diretórios certos na raiz do aplicativo web.

É aí que o pacote PHP Composer Asset Manager entra em ação. Uma das principais necessidade que ele atende é a instalação de arquivos assests na pasta, ou sub-pasta correta do documento web.

Usando o plugin Composer Asset Manager

A primeira coisa que você precisa fazer para usar o pacote Composer Asset Manager é acrescentá-lo a seu arquivo composer.json do seu projeto.

Como você pode ver abaixo, é preciso acrescentar os pacotes phpclasses/assets à seção require do seu projeto. Esse é um pacote fictício que aciona o carregamento do plugin.

Por exemplo, as ações abaixo dizem ao plugin para instalar todos os arquivos JavaScript no diretório web/js. O plugin criará todos os subdiretórios caso eles não existam.

 {
  "name": "your-project-name-here",

  "require":
   {
    "phpclasses/assets": "*",
     ... list other required packages here ...
    "jsclasses/fast-content-loader": "*"
   },

   "repositories":
   [
    {
     "type": "composer",
     "url": "http://www.phpclasses.org/"
    },

    ... other repositories definition goes here ...

    {
     "type": "composer",
     "url": "http://www.jsclasses.org/"
    }
   ]

   "extra":
   {
    "assets":
    {
     ... your assets installation definitions go here ...

     "actions":
     [
      {
       "js-target": "web/js"
      }
     ],

     "packages":
     {
      "jsclasses/fast-content-loader":
      {
      }
     }

    }
   }
  }

Como pode ser visto acima, as definições de onde você quer os assets devem ser incluídas na seção extra. Ela deve conter uma entrada nomeada de assets que define quaisquer ações de instalação que você precise realizar.

A seção assets precisa especificar quais pacotes, de todos que você está usando no seu projeto, possuem os arquivos asset que você quer instalar. No exemplo, ele apenas instala os assets do pacote jsclasses/fast-content-loader.

Cada pacote pode ter ações de instalação específicas associadas. Essas ações precisam ser definidas em uma seção nomeada actions, dentro das definições do pacote. No exemplo, essa seção está vazia para o pacote jsclasses/fast-content-loader. Isso significa que não há ações específicas de instalação para serem realizadas.

Entretanto, você pode definir ações para todos os pacotes na seção assets nomeada actions. Isso quer dizer que uma seção pode listar uma ou mais ações para serem executadas.

Todas as ações precisam ter uma entrada type definida explicita ou implicitamente. Isso define o nome da ação. Atualmente, apenas a ação copy é suportada. Outras ações podem vir a ser suportadas no futuro.

A ação copy diz ao plugin para copiar os arquivos assests para um diretório definido na entrada target. A entrada pattern define a expressão regular que combina os nomes dos arquivos que serão copiados.

   "extra":
   {
    "assets":
    {
     ... your assets installation definitions go here ...

     "actions":
     [
      {
       "type": "copy",
       "target": "web/js",
       "pattern": "\\.jsquot;
      }
     ],

     "packages":
     {
      "jsclasses/fast-content-loader":
      {
      }
     }

    }
   }

Para simplificar, você pode definir aquela ação com uma simples entrada nomeada de js-target. Você também pode usar css-target como entrada para copiar arquivos CSS ou image-target para copiar arquivos de imagem JPEG, PNG e GIF.

     "actions":
     [
      {
       "js-target": "web/js"
      }
     ]

Implementando novos tipos de ações e instalação

Como mencionado acima, no futuro, outros tipos de ações serão implementadas para a instalaçãoção de assets, como copiar e minimizar arquivos JavaScript ou CSS, otimizar de imagens, ou criar sprites a partir de um conjunto de arquivos de imagens.

Enquanto isso, você pode implementar suas próprias ações personalizadas ao criar um novo plugin que estende as funcionalidades. Simplesmente crie um novo pacote com uma classe que estende a classe mlemos\Composer\AssetInstaler e sobrescreva a função installAction.

 public function installAction(PackageInterface $package, $action)
 {
  // return true if the parent class implements this action
  if(parent::installAction($package, $action))
   return true;

  switch($action['type'])
  {
   case 'some-action-namespace/some-action-name':

    // Your action code goes here

    // Return true to tell that your plugin implemented this action
    return true;
  }

  // Return fall to tell that your plugin does not implement this action
  return false;
 }

Tenha certeza de que o nome da ação de instalação que você implementar possui um prefixo único, como alguma-ação-namespace/ desse exemplo. Isso é para evitar a colisão de nomes de ações no caso de você implementar ações que possuem o mesmo nome de futuras ações a serem implementadas pelo plugin.

Login automático para repositórios que precisam de senha

Outra necessidade que o Composer atual não resolve é o login automático em repositórios que necessitam de autenticação. Atualmente, o Composer exige que você digite manualmente seu nome de usuário e senha cada vez que acessa esses repositórios. Essa é uma tarefa tediosa.

No passado, era necessário aplicar um patch no Composer para fazê-lo ler nomes de usuários e senhas de um arquivo de configuração separado. Entretanto, essa não é uma solução ideal, porque nem todo mundo pode utilizar uma versão do Composer com um patch aplicado.

Felizmente, esse plugin fornece a solução para o problema. Ele pode ler o arquivo de configuração e definir os nomes de usuário e senhas necessários para repositórios que precisam de autenticação. Dessa forma, o usuário não precisa digitá-los no shell (a não ser que estejam incorretos).

Normalmente, os arquivos de configuração precisam estar localizados no diretório do projeto com o nome auth.json. Por razões de segurança, você talvez queira remover esses arquivos depois da instalação de seu servidor de produção, para minimizar danos de segurança no caso de ele ser comprometido.

Aqui está um exemplo de arquivo de configuração de autenticação:

 {
  "config":
  {
   "basic-auth":
   {
    "www.jsclasses.org":
    {
     "username": "your-user-name",
     "password": "your-JS-Classes-composer-repository-token-password"
    },
    "www.phpclasses.org":
    {
     "username": "your-user-name",
     "password": "your-PHP-Classes-composer-repository-token-password"
    }
   }
  }
 }

É possível que o recurso de autenticação automática desse plugin não seja mais necessário no futuro, pois há um patch submetido via pull request por Stephan Hochdörfer para implementar um recurso similar diretamente no Composer. Até que esse patch seja incluído no programa, esse plugin continuará a ser útil.

Conclusão

Conforme você deve ter aprendido neste artigo, é possível estender o Composer para torná-lo ainda mais útil do que ele é hoje. Muito obrigado aos autores do Composer, Jordi Boggiano, Nils Adermann e muitos outros que contribuíram para o seu desenvolvimento e para estendê-lo com plugins de terceiros.

Eu gostaria de agradecer especialmente a Stephan Hochdörfer, do bitExpert, por ser tão prestativo com seu conhecimento, que contribuiu para tornar esse plugin possível.

Esse plugin é de código aberto e está disponível para download e instalação sem a necessidade de se registrar no site do PHP Classes. Sinta-se livre para usá-lo e copiá-lo para seu próprio ambiente se necessário. Se você redistribuí-lo, apreciaríamos se você linkasse este artigo para que outros usuários possam aprender como usá-lo.

Além disso, poste um comentário caso você tenha comentários, perguntas ou sugestões que gostaria de fazer sobre o plugin.

***

Artigo traduzido pela Redação iMasters, com autorização do autor. Publicado originalmente em http://www.phpclasses.org/blog/package/8429/post/1-Using-Composer-to-Install-JavaScript-CSS-and-Images-Under-the-Web-Document-Directory.html