Uma vez que erigir seu primeiro pacote PHP

Se você quiser fabricar um pacote PHP do zero e compartilhá-lo com outros desenvolvedores PHP, Compositor é um gerenciador de dependências que torna o processo fácil! Graças ao Composer, o PHP tem um dos principais ecossistemas de pacotes. Vamos submergir juntos e percorrer as etapas para fabricar um pacote PHP.

#Começando

O foco principal deste cláusula é ajudar aqueles que são novos em PHP (ou novos na escrita de pacotes PHP) que querem aprender porquê fabricar pacotes PHP do zero.

Há algumas coisas que precisamos realizar porquê segmento da forma de um novo pacote PHP:

• Inicializar um repositório Git
• Crie e configure um composer.json registo
• Instalar dependências
• Configurar carregamento automático

Embora pudéssemos iniciar criando um projeto vazio no GitHub e clonando-o localmente, criaremos uma novidade pasta localmente, inicializaremos o projeto e, em seguida, enviaremos o código-fonte para o GitHub:

$ mkdir example-package
$ cd ./example-package
$ git init
$ echo "/vendor/" >> .gitignore
$ composer init
$ git add .
$ git commit -m"First Commit"
# later you can add a remote and push the source code

O composer init comando o guiará pela forma do seu projeto interativamente, definindo valores porquê o nome do pacote, autores e licença, e pesquisando por dependências de pacotes. Sinta-se à vontade para preenchê-los, mas para ser breve, cá está nosso ponto de partida:

{
    "name": "laravelnews/feeds",
    "description": "Get articles from Laravel-News.com",
    "type": "library",
    "require": {}
}

Temos a forma básica para um pacote, mas isso não vai realizar muita coisa. Alguns pacotes não precisam exigir nenhuma submissão se o pacote usar unicamente a linguagem PHP principal. De qualquer forma, você precisará configurar o carregamento automático para que os usuários do seu pacote possam carregar as funções e classes em seus projetos.

Quando estiver pronto para conectar seu checkout lugar a um VCS porquê o GitHub, você pode seguir as instruções para somar um remoto. Pode parecer similar ao comando a seguir:

git remote add origin [email protected]:laravelnews/example-package.git

#Configurando o carregamento automático

Depois de fabricar o imprescindível composer.json estrutura, podemos prosseguir para a geração do código-fonte. Você precisará resolver onde deseja armazenar Sua visita nos ajuda a continuar oferecendo o melhor para você! código-fonte dentro do seu projeto. A pasta pode ser chamada de qualquer coisa que você quiser, mas o “padrão” típico é src/ ou lib/. O Composer não se importa com qual(is) caminho(s) você usa, no entanto, você precisa instruir o Composer onde ele pode carregar maquinalmente os arquivos usando PSR-4. Vamos usar o src pasta e crie uma classe para nosso pacote de exemplo:

$ mkdir src/
$ touch src/Api.php

Em seguida, abra o composer.json arquivar e configurar o autoloader usando o "autoload" chave:

{
    "name": "laravelnews/feeds",
    "description": "Get articles from Laravel-News.com",
    "type": "library",
    "require": {},
    "autoload": {
        "psr-4": {
            "LaravelNewsFeed": "src/"
        }
    }
}

As propriedades dentro do autoload.psr-4 mapeia os namespaces PHP para pastas. Quando criamos arquivos no src pasta, eles serão mapeados para o LaravelNewsFeed namespace. Para oriente exemplo, criamos um Api.php registo que solicita e retorna o feed JSON do Laravel News. Se você estiver acompanhando, adicione o seguinte código ao src/Api.php:

 
namespace LaravelNewsFeed;
 
class Api
{
    public function json(): array
    {
        $json = file_get_contents('https://laravel-news.com/feed/json');
 
        return json_decode($json, true);
    }
}

Uma vez que podemos testar nossa novidade classe agora mesmo?

Existem algumas maneiras, porquê exigir oriente pacote em outro projeto por meio de dependências locais do Composer ou até mesmo enviar o código para o GitHub e fazer uma composer update em nosso pacote usando dev-main. No entanto, também podemos simplesmente fabricar um índice.php registo na raiz do projeto para testá-lo:

 
use LaravelNewsFeedApi;
 
require __DIR__.'/vendor/autoload.php';
 
$response = (new Api)->json();
 
echo "The Laravel-News.com feed has returned ".count($response['items']['items'])." items.n";
// ...

Exigimos o autoloader do Composer, que sabe porquê carregar os arquivos para o nosso pacote. Para o Composer entender porquê encontrar nossos arquivos, precisamos executar composer install:

$ composer install
# or
$ composer dump-autoload
$ php índice.php
The Laravel-News.com feed has returned 20 items.

Você também pode executar o dump-autoload comando para atualizar o autoloader do Composer depois somar o namespace a composer.json.

Executando o índice.php file nos permite iniciar a trabalhar rapidamente com nosso pacote, no entanto, também podemos iniciar a usar nosso código criando um conjunto de testes. Vamos submergir na forma!

#Testes de pacotes e dependências de desenvolvimento

Recomendo ortografar testes para qualquer projeto em que você trabalhe, e paladar de configurar os testes o mais cedo verosímil. Ao fabricar um pacote PHP, o framework de teste mais generalidade é o PHPUnit. Minha opção favorita ultimamente é o Pest PHP, e acho que você vai apaixonar porquê é fácil de configurar!

Os pacotes do Composer têm dois conjuntos de requisitos: require a seção inclui pacotes que são necessários para que seu pacote seja executado e require-dev inclui pacotes que são necessários para teste. Até agora, não temos nenhum require pacotes, e isso pode ocorrer se você não quiser ou precisar de nenhuma outra submissão de pacote.

Duvido que você queira ortografar sua própria estrutura de teste do zero, portanto estamos prestes a instalar nossa primeira submissão de desenvolvimento. Também não queremos sempre fazer solicitações para um endpoint JSON ativo, portanto também instalaremos uma livraria de simulação (Mockery) para simular chamadas HTTP:

$ composer require pestphp/pest --dev --with-all-dependencies
$ composer require --dev mockery/mockery

Dica: Recomendo configurar a classificação de pacotes para manter suas dependências organizadas por meio da seguinte opção de forma em composer.json:

"config": {
    "sort-packages": true
}

Depois instalar o Pest e o Mockery, podemos inicializar o Pest através do --init bandeira. Uma vez que os arquivos são criados, podemos executar pest para testar nosso código:

vendor/bin/pest --init
# ...
vendor/bin/pest
   PASS  TestsFeatureExampleTest
  ✓ example
 
   PASS  TestsUnitExampleTest
  ✓ example
 
  Tests:    2 passed (2 assertions)
  Duration: 0.06s

Você pode organizar os testes do seu pacote da maneira que quiser, e eu recomendo verificar o Documentação de pragas para obter detalhes completos sobre porquê configurar o Pest.

Em seguida, vamos fabricar uma classe simples que podemos usar para provar um teste de pacote. Essa classe obterá artigos recentes do feed JSON do Laravel News e retornará o cláusula mais recente.

Chamaremos essa classe fictícia NewsChecker e adicione-o ao src/NewsChecker.php registo com o seguinte teor:

 
namespace LaravelNewsFeed;
 
class NewsChecker
{
 
    public Sua visita nos ajuda a continuar oferecendo o melhor para você! style="color: #D73A49;">function __construct(
        private Api $api
    ) {}
 
    public function latestArticle(): array
    {
        $response = $this->api->json();
        $items = $response['items']['items'] ?? [];
 
        if (empty($items)) {
            throw new Exception("Unable to retrieve the latest article from Laravel-News.com");
        }
 
        usort($items, function($a, $b) {
            return strtotime($b['date_published']) - strtotime($a['date_published']);
        });
 
        return $items[0];
    }
}

Note que ele leva o Api class porquê uma submissão, que iremos simular em nosso teste.

Em seguida, criaremos oriente registo em tests/Feature/NewsCheckerTest.php arquivar e somar os seguintes testes para validar o latestArticle() método:

use LaravelNewsFeedApi;
use LaravelNewsFeedNewsChecker;
 
it('Returns the latest article on Laravel-News.com', function () {
    $items = [
        [
            'id' => 3648,
            'title' => "Laravel SEO made easy with the Honeystone package",
            'date_published' => "2024-08-20T13:00:00+00:00",
        ],
        [
            'id' => 3650,
            'title' => "LCS #5 - Patricio: Mingle JS,  PHP WASM, VoxPop",
            'date_published' => "2024-08-23T13:00:00+00:00",
        ],
        [
            'id' => 3647,
            'title' => "Laravel Model Tips",
            'date_published' => "2024-08-22T13:00:00+00:00",
        ],
    ];
 
    $api = Mockery::mock(Api::class);
    $api->shouldReceive('json')->once()->andReturn([
        'title' => 'Laravel News Feed',
        'feed_url' => 'https://laravel-news.com/feed/json',
        'items' => [
            'items' => $items,
        ],
    ]);
 
    $checker = new NewsChecker($api);
    $article = $checker->latestArticle();
 
    expect($article['title'])->toBe("LCS #5 - Patricio: Mingle JS,  PHP WASM, VoxPop");
});
 
it('Throws an exception if no items are returned from the feed', function () {
    $api = Mockery::mock(Api::class);
    $api->shouldReceive('json')->once()->andReturn([
        'title' => 'Laravel News Feed',
        'feed_url' => 'https://laravel-news.com/feed/json',
    ]);
 
    $checker = new NewsChecker($api);
 
    expect(fn() => $checker->latestArticle())
        ->toThrow(new Exception('Unable to retrieve the latest article from Laravel-News.com'));
});

Você pode executar esses testes e validar se o código funciona executando vendor/bin/pest. Sinta-se à vontade para excluir os testes de exemplo criados depois a realização pest --init.

Cobrimos bastante terreno, desde a inicialização de um repositório Git, configurando o pacote PHP com composer.jsonadicionando código manancial e testes, e executando-os com Pest. A partir daqui, você está pronto para publicar seu pacote no Packagist!

#Saber mais

Recomendo que você se inscreva e confira a documentação em Packagist.orgonde você publicará novas versões do seu pacote. O processo de atualização das versões do seu pacote no Packagist pode ser automatizado, o que significa que quando você marca novas versões do seu pacote, elas aparecerão maquinalmente no Packagist.org.

Percorremos o caminho da geração de um pacote do zero, mas se você estiver usando o GitHub, crie um repositório de modelos para sua organização ou projetos pessoais pode apressar as coisas ainda mais! Existem alguns esqueletos de pacotes de destaque da comunidade que você pode usar porquê ponto de partida para seu próximo pacote Composer: