Tutorial de como criar um módulo para Magento

Neste tutorial, vou mostrar como é o desenvolvimento de um módulo para plataforma de e-commerce open source Magento.

O funcionamento final deste módulo ensinado no tutorial é extremamente simples. A principal idéia é apresentar o funcionamento do Magento, como seria os primeiros passar para o desenvolvimento de um módulo mas complexo para o Magento.

O tópicos que serão apresentados no tutorial são:

  • A pasta app/code;
  • A estrutura e criação de um Módulo para Magento;
  • O padrão Observer do Magento;
  • Criando Logs;

Antes de iniciar o tutorial

Ao iniciar este tutorial, pressumimos que você já tenha o Magento instalado e rodando no seu servidor de desenvolvimento, e que você tenha permissão para adicionar novos arquivos a estrutura do Magento.

A versão do sistema instalada não fará diferença para este tutorial, pois o conteúdo apresentado é de fundamentos do sistema, e estão presentes em todas versões do sistema: Community, Professional e Enterprise.

Desabilitando o cache

A primeira lição para todo desenvolvedor Magento é desabilitar o cache. Isso deve ser feito pelo painel de administração do sistema, seguindo os passos: Painel de Administração → Sistema → Gerenciamento de Cache → Selecionar Tudo → Ações: Desabilitar → Enviar.

O cache é o principal amigo quando a loja está no servidor de produção, melhorando muito a performance. Mas para o desenvolvedor, é o maior inimigo. Qualquer desenvolvedor de Magento já passou pela experiência de não visualizar suas modificações na loja, pelo simples problema do cache estar ativado! Então isso deve ser o primeiro passo a seguir.

A pasta app/code

Os principais arquivos do Magento podem ser encontrados em módulos individuais dentro da pasta app/code, que é dividida em três zonas: community, core e local.

CORE

O app/code/core é a pasta onde encontra-se todas as funcionalidades de produtos, categorias, clientes, pagamentos e etc. Até mesmo se você saiba o que está fazendo, NÃO deve modificar arquivos presente nessa pasta.

O Magento é estruturado de uma maneira onde você pode alterar a funcionalidade de qualquer um desses arquivos sem precisar modificá-los diretamente, garantindo que sua aplicação continue a prova de atualizações do CORE.

COMMUNITY

Como o próprio nome sugere, a pasta app/code/community é o lugar onde deve estar os módulos fornecidos por terceiros (ou seja, equipe não oficial do Magento). Estes módulos podem ser encontrados para baixar na Magento Connect, e podem ser baixados diretamente pelo “Downloader” do sistema.

LOCAL

A pasta app/code/local é o caminho que vem vazio na instação do Magento. É o local onde deve ficar os módulos feitos sobre medida para sua instalação Magento. Este é o lugar onde vamos estar trabalhando para a construção do exemplo neste tutorial.

Estruturando o módulo

Vamos iniciar a estruturação do módulo. Para isso, abra o seu editor de arquivos preferido e navegue até a pasta app/code/local onde vamos criar novas pastas e arquivos.

Definindo o “Namespace” do módulo

O termo “Namespace” é usado para definir o local onde ficará o módulo na pasta local. Por convenção, o nome usado é da empresa que vai desenvolver o módulo, ou o próprio nome do módulo. O Magento usa o “namespace” Mage. Para este tutorial vamos criar o “namespace” DicasDePhp. Então, o próximo passo é criar a pasta, app/code/local/DicasDePhp.

Nome do Módulo

A próxima pasta a ser criada será a do nosso módulo. Com isso, vamos usar o nome do nosso próprio módulo. Como vamos desenvolver um que irá criar logs a cada vez que um produto é criado ou atualizado, o nome do módulo será ProdutoLogs. Criaremos a pasta app/code/local/DicasDePhp/ProdutoLogs.

Fazendo uma pequena revisão até o momento, vamos ter a seguinte árvore de pastas criadas. Lembrando que essa criação de pastas é case-sensitive, com isso é importante capitalizar as palavras conforme abaixo:

app
   -code
      --local
         ---DicasDePhp
            ----ProdutoLogs

O próximo passo é criar as configurações do nosso módulo. Para isso vamos criar uma pasta chamada etc, onde ficará os arquivos XML responsáveis pelas configurações dos módulos. Com isso criamos o arquivos app/code/local/DicasDePhp/ProdutoLogs/etc/config.xml.

Este arquivo é responsável por mostrar para o Magento onde encontra-se os arquivos do módulo, versão e eventos do sistema a observar. Por enquanto vamos apenas criar o arquivo simples, conforme código abaixo:

<?xml version="1.0" encoding="UTF-8"?>
<!-- O nó raiz para a configuração do módulo Magento -->
<config>
    <!-- Nó do módulo contém informações básicas sobre cada módulo Magento -->
    <modules>
        <!--
            Este nó deve corresponder exatamente o nome do namespace e módulos,
            separando as pastas com underline.
        -->
        <DicasDePhp_ProdutoLogs>
            <!-- A versão do módulo. Estamos iniciando na versão 0.0.1 -->
            <version>0.0.1</version>
        </DicasDePhp_ProdutoLogs>
    </modules>
</config>

Ativando o módulo

O próximo passo é ativar o módulo. Para isso precisamos dizer ao Magento que ele existe, criando um arquivo XML na pasta de módulos do sistema app/etc/modules. O nome do arquivo XML pode ser o de sua preferência. De qualquer maneira o Magento irá ler todos os arquivos presentes na pasta, e interpretar o conteúdo desses arquivos.

Mas por conveção, vamos manter o nome do módulo, evitando que tenhamos arquivos “perdidos” na pasta de módulos do sistema. Vamos criar app/etc/modules/DicasDePhp_ ProdutosLog.xml com o seguinte conteúdo:

<?xml version="1.0" encoding="UTF-8"?>
<config>
    <modules>
        <DicasDePhp_ProdutoLogs>
            <!-- Dizemos se o módulo está ativo: true or false -->
            <active>true</active>
            <!-- Qual local o módulo está criado. -->
            <codePool>local</codePool>
        </DicasDePhp_ProdutoLogs>
    </modules>
</config>

Verificando o módulo

Agora já podemos verificar se a instalação feita até o momento está funcionando. Claro que o módulo não executa nenhuma ação até o momento, mas é possível ver se o Magento identificou corretamente o módulo ProdutoLogs. Para isso, é necessário fazer o seguinte caminho no sistema: Painel de Administração → Sistema → Configurações → Avançado → Avançado.

Nesta tela, haverá a opção de visualizar os módulos ativos no sistema. O módulo DicasDePhp_ProdutoLogs deverá estar presente na lista. Caso não esteja, pode haver algo errado na configuração.

O primeiro passo é verificar o cache do Magento, se ele está desabilidado. Caso ele esteja desabilidado, volte alguns passos e verifique novamente o que pode estar errado no seu módulo.

Vamos ver qual a estrutura de nosso módulo até o momento:

app
   -code
      --local
         ---DicasDePhp
            ----ProdutoLogs
               -----etc
                  ------config.xml

   -etc
      --modules
         ---DicasDePhp_ProdutoLogs.xml

Definindo o Evento Observer

O evento Observer é uma ferramenta poderesa e rápida para você conseguir extender funcionalidades do sistema, podendo assim fazer rewrite ou overwrite de qualquer método ou classe. O que queremos observar neste módulo do tutorial, é ação que o sistema dispara ao após salvar um produto no painel de administração. Então, o código que nós interessa é catalog_product_save_after. Descobrir qual ação precisamos cobrir requer um conhecimento mais avançado das regras de negócio do Magento. Isso foge do escopo desse tutorial, mas vou mostrar em outro post, fiquem tranquilos.

Agora, vamos precisar modificar o arquivo config.xml de nosso módulo, conforme abaixo:

<?xml version="1.0" encoding="UTF-8"?>
<!-- O nó raiz para a configuração do módulo Magento -->
<config>
    <!-- Nó do módulo contém informações básicas sobre cada módulo Magento -->
    <modules>
        <!--
            Este nó deve corresponder exatamente o nome do namespace e módulos,
            separando as pastas com underline.
        -->
        <DicasDePhp_ProdutoLogs>
            <!-- A versão do módulo. Estamos iniciando na versão 0.0.1 -->
            <version>0.0.1</version>
        </DicasDePhp_ProdutoLogs>
    </modules>
    <!-- Configuramos o módulo para ter comportamento no escopo global do sistema -->
    <global>
        <!-- Definindo o evento observer -->
        <events>
            <!-- O código do evento que queremos observar -->
            <catalog_product_save_after>
                <!-- Definição de um observador para este evento -->
                <observers>
                    <!--
                        Identificador único no nó catalog_product_save_after.
                        Por convenção, colocamos o nome do módulo em minúsculo.
                    -->
                    <dicasdephp_produtologs>
                        <!-- O modelo a ser instanciado -->
                        <class>dicasdephp_produtologs/observer</class>
                        <!-- O método do modelo acima, para ser chamado -->
                        <method>logUpdate</method>
                        <!-- Geralmente usam o tipo singleton para os observadores -->
                        <type>singleton</type>

                    </dicasdephp_produtologs>
                </observers>
            </catalog_product_save_after>
        </events>
    </global>
</config>

Configurando a pasta dos models

No evento que definimos acima, fizemos referência a um model que ainda não está criado no tutorial. Precisamos mostrar para o Magento onde encontrar nossos models, atualizando o arquivo config.xml com o seguinte código:

<?xml version="1.0" encoding="UTF-8"?>
<!-- O nó raiz para a configuração do módulo Magento -->
<config>
    <!-- Nó do módulo contém informações básicas sobre cada módulo Magento -->
    <modules>
        <!--
            Este nó deve corresponder exatamente o nome do namespace e módulos,
            separando as pastas com underline.
        -->
        <DicasDePhp_ProdutoLogs>
            <!-- A versão do módulo. Estamos iniciando na versão 0.0.1 -->
            <version>0.0.1</version>
        </DicasDePhp_ProdutoLogs>
    </modules>
    <!-- Configuramos o módulo para ter comportamento no escopo global do sistema -->
    <global>
        <!-- Definindo os models -->
        <models>
            <!--
                Identificador único no nó de models.
                Por convenção, colocamos o nome do módulo em minúsculo.
            -->
            <dicasdephp_produtologs>
                <!--
                    O caminho para o nosso diretório de modelos,
                    com separadores de diretório substituído por underlines
                -->
                <class>DicasDePhp_ProdutoLogs_Model</class>
            </dicasdephp_produtologs>
        </models>

   		<!-- Definindo o evento observer -->
        <events>
            <!-- O código do evento que queremos observar -->
            <catalog_product_save_after>
                <!-- Definição de um observador para este evento -->
                <observers>
                    <!--
                        Identificador único no nó catalog_product_save_after.
                        Por convenção, colocamos o nome do módulo em minúsculo.
                    -->
                    <dicasdephp_produtologs>
                        <!-- O modelo a ser instanciado -->
                        <class>dicasdephp_produtologs/observer</class>
                        <!-- O método do modelo acima, para ser chamado -->
                        <method>logUpdate</method>
                        <!-- Geralmente usam o tipo singleton para os observadores -->
                        <type>singleton</type>
                    </dicasdephp_produtologs>
                </observers>
            </catalog_product_save_after>
        </events>
    </global>
</config>

Criando um Observer Model

Agora vamos criar o arquivo que irá ser instanciado no momento que o evento for disparado.

Para isso vamos criar o arquivo app/code/local/DicasDePhp/ProdutoLogs/Model/Observer.php, com o seguinte código:

<?php

class DicasDePhp_ProdutoLogs_Model_Observer {

    /**
     * O Magento irá passar a Varien_Event_Observer object como
     * o primeiro parâmetro de eventos despachados.
     */
    public function logUpdate(Varien_Event_Observer $observer) {
        // Recuperar o produto que está sendo atualizado a partir do observador evento
        $product = $observer->getEvent()->getProduct();

        // Escrevendo uma nova linha no var/log/product-updates.log
        $name = $product->getName();
        $sku = $product->getSku();
        Mage::log("{$name} ({$sku}) updated", null, 'atualizacoes-produtos.log');
    }

}

 OK, está pronto!

Com isso, chegamos ao final do tutorial. Se todos os passos foram seguidos corretamente, você deve ter a estrutura abaixo:

app
   -code
      --local
         ---DicasDePhp
            ----ProdutoLogs
               -----Model
                  ------Observer.php

               -----etc
                  ------config.xml

   -etc
      --modules
         ---DicasDePhp_ProdutoLogs.xml

Agora, cada vez que você salvar ou criar um produto no Magento, um registro de log deve ser criado na pasta var/log, dentro do arquivo atualizacoes-produtos.log.

Se o arquivo não aparecer na pasta, procure verificar as permissões de escrita da pasta que o sistema tem. Ainda é necessário verificar se no Magento está habilitado para exibir os logs. O caminho para isso é Painel de Administração → Sistema → Configurações → Desenvolvedor → Configurações de Log → Ativar.

A idéia desse tutorial é mostrar um pouco do funcionamento do Magento. Após desenvolver este tutorial, recomendamos que você passe um tempo explorando a pasta app/code/core do Magento, assim você vai poder ter uma boa idéia de todo o funcionamento do sistema.

Você pode baixar o módulo deste tutorial:
– ProdutoLogs.

Dúvidas e feedback são bem vindos, é só deixar um comentário!

Este tutorial foi escrito originalmente no blog Smashing Magazine, por . Traduzido e adaptado para o Dicas de PHP por Fausto Schneider.