Agregar Composer a un sitio existente

Simplificado en Drupal 8.8.0

Nota: si comenzaste tu proyecto usando Drupal versión 8.8.0 o superior, tu sitio ya utiliza la estructura de archivos correcta y está listo para ser convertido a Composer.

Esta página es una guía paso a paso para agregar soporte de Composer manualmente a un sitio existente que fue instalado previamente sin Composer. Esta guía es para ti si instalaste Drupal 8 manualmente desde un archivo o usaste una plantilla Composer obsoleta, como drupal/drupal.

Para sitios creados con Drupal 8.8.0 o superior

Incluso si instalaste Drupal 8.8.0 desde un archivo, Composer ya viene preinstalado. Por lo tanto, deberías poder administrar tu sitio con Composer sin necesidad de pasos adicionales para convertir el sitio.

Para sitios creados antes de Drupal 8.8.0

El archivo composer.json que viene con los archivos descargados desde https://www.drupal.org/download antes de Drupal 8.8.0 no estaba destinado a usarse con un sitio gestionado por Composer.

Si quieres cambiar de gestión manual a usar Composer para instalar y actualizar el núcleo de Drupal y los módulos adicionales, primero necesitas modificar el archivo composer.json de tu sitio.

Errores típicos de Composer que indican un archivo composer.json incorrecto incluyen:

Nothing to install or update (even though updates exist)

Installation request for drupal/drupal No version set (parsed as 1.0.0) -> satisfiable by drupal/drupal[No version set (parsed as 1.0.0)].

don't install drupal/core 8.x.x | remove drupal/drupal No version set (parsed as 1.0.0)

Your requirements could not be resolved to an installable set of packages.

A veces los problemas con plantillas Composer se resuelven eliminando el archivo de bloqueo de Composer y el directorio vendors (composer.lock y vendor/) antes de ejecutar la actualización de Composer, pero convertir un sitio Drupal 8 existente a un proyecto gestionado con la plantilla Composer recomendada en la Guía de instalación de Drupal 8 (3.5. Usar Composer para descargar y actualizar archivos) es una solución más robusta para los problemas de actualización de Drupal.

Las herramientas gocomposer y composerize drupal intentan automatizar la conversión de sitios antiguos a proyectos Composer, pero convertir manualmente es bastante simple incluso para sitios grandes y no toma mucho tiempo.

Al final del proceso, tu proyecto tendrá la estructura de directorios recomendada. La configuración de Composer (composer.json, composer.lock, etc.), Drush y el directorio vendors estarán fuera de tu webroot. Tu webroot original contendrá una nueva carpeta llamada web/, que contendrá el sitio web real. Si tu proyecto actualmente usa otra estructura de directorios, tendrás que actualizar la configuración de tu servidor web para que apunte a la nueva carpeta web/. Volveremos a esto más adelante.

¿Resumiendo?

1. Instala un nuevo sitio Drupal usando la plantilla Composer actual en un directorio nuevo.
2. Copia todos los temas personalizados, módulos, archivos y configuraciones a tu nuevo proyecto. (Verifica dos veces la estructura de directorios.)
3. Migra las configuraciones a tu nuevo proyecto.
4. Agrega todos los módulos adicionales a tu nuevo archivo composer.json y ejecuta la instalación con composer.
5. Actualiza la base de datos y limpia la caché (drush updb; drush cr).
6. Actualiza la configuración de tu servidor web.

Historia completa

Estas instrucciones asumen que tu sitio web actual está en /var/www/sites/html/ y que crearás un nuevo sitio en /var/www/sites/new_html/. Ajusta las rutas a tus directorios reales.

Antes de empezar

Si vas a "componer" (gestionar con Composer) el núcleo y los módulos contribuidos de un sitio Drupal antiguo, probablemente no estén en sus versiones más recientes. Si sigues esta guía a ciegas, el núcleo y todos los módulos se actualizarán a las últimas versiones. Esto probablemente es lo que quieres, pero considera la configuración de tu sitio. ¿Hay razones para no actualizar todo a las versiones más recientes? Puede que tengas una instalación que dependa de una versión antigua de alguna librería o módulo que no debería actualizarse.

Si quieres actualizar todo a la última versión, simplemente sigue esta guía y resuelve los problemas después de completar la actualización. Probablemente verás algunos errores o advertencias relacionados con versiones más nuevas de módulos; simplemente busca esas advertencias en Google y verifica si hay parches o correcciones.

Si prefieres mantener tus versiones originales y luego actualizar usando Composer, debes asegurarte de requerir las mismas versiones de módulos, núcleo y dependencias que usabas en el sitio antiguo. Consulta las guías de composer create-project para cómo descargar una versión específica del núcleo o versiones específicas de módulos contrib. Finalmente, asegúrate de indicar esas versiones antes de correr composer create-project o composer require (p. ej. composer require vendor/package:version).

1. Instala un nuevo sitio Drupal

Crea un nuevo proyecto Drupal usando la plantilla drupal/recommended-project:

cd /var/www/sites
composer create-project drupal/recommended-project:~8.8.0 new_html --stability dev --no-interaction

Esto creará el directorio new_html/ en el directorio actual, con las carpetas vendors y web (= webroot), y tus archivos composer.json, etc. Si tu proyecto antiguo no usaba esta estructura, tendrás que acostumbrarte a correr drush y composer desde este directorio, no solo desde la raíz.

Anteriormente se recomendaba usar drupal-composer/drupal-project, pero ahora está obsoleto en favor de la plantilla oficial: drupal/recommended-project.

2. Copia archivos al nuevo proyecto Composer

Nota. Estas instrucciones aplican solo para sitios creados antes de Drupal 8.8.0.

Si tu proyecto fue creado antes de Drupal 8.8.0, ahora debes copiar tus módulos personalizados, temas y librerías desde el antiguo directorio al nuevo proyecto. Asegúrate de colocarlos en los directorios correctos en tu nuevo proyecto, ya que la estructura de carpetas antigua puede ser diferente.

Los caminos correctos se pueden encontrar en la sección "installer-paths" de tu composer.json:

"extra": {
    "composer-exit-on-patch-failure": ...,
    "patchLevel": {
        ...
    },
    "installer-paths": {
        "web/core": ["type:drupal-core"],
        "web/libraries/{$name}": ["type:drupal-library"],
        "web/modules/contrib/{$name}": ["type:drupal-module"],
        "web/profiles/contrib/{$name}": ["type:drupal-profile"],
        "web/themes/contrib/{$name}": ["type:drupal-theme"],
        "drush/Commands/{$name}": ["type:drupal-drush"]
    },
    "drupal-scaffold": {
        ...
    }
}

En tu sitio antiguo, los módulos probablemente estaban en /var/www/sites/html/modules/. En el nuevo sitio deben ir en la ruta indicada en la sección de installer-paths, por ejemplo /var/www/sites/new_html/web/modules/.

• Los temas personalizados están en /var/www/sites/new_html/web/themes/custom/
• Los módulos personalizados están en /var/www/sites/new_html/web/modules/custom/
• Las librerías están en /var/www/sites/new_html/web/libraries/
• Los archivos e imágenes subidos están en /var/www/sites/new_html/web/sites/default/files/

Verifica que el servidor web tenga permisos de escritura para el directorio de archivos, igual que cuando instalaste un sitio nuevo. Consulta la sección Protección de permisos y propiedad de archivos para más detalles.

Asumiendo que el usuario de tu servidor web es www-data y el usuario FTP es vftp, ejecuta comandos similares a estos para establecer permisos correctos:

# Establece el grupo de la carpeta files al usuario del servidor web
sudo chown -R vftp:www-data /var/www/sites/new_html/web/sites/default/files

# Permite al grupo del servidor web editar y acceder a directorios dentro de files
sudo find /var/www/sites/new_html/web/sites/default/files -type d -exec chmod u=rwx,g=rwx,o= '{}' \;

# Permite al grupo del servidor web editar todos los archivos dentro de files
sudo find /var/www/sites/new_html/web/sites/default/files -type f -exec chmod u=rw,g=rw,o= '{}' \;

Tu carpeta files contiene todos los archivos subidos por los usuarios a tu sitio antiguo, además de algunas carpetas con archivos temporales como hojas de estilos comprimidas o plantillas cacheadas.

Si copiaste estas carpetas temporales desde el sitio antiguo al nuevo directorio files, asegúrate de eliminarlas manualmente. Estas carpetas suelen ser php/, js/, styles/ y css/ dentro de /var/www/sites/new_html/web/sites/default/files. Normalmente estos archivos se regeneran automáticamente tras limpiar la caché (drush cr) y visitar el sitio con el navegador, así que no te preocupes al eliminarlos. Pero siempre asegúrate de tener una copia de seguridad antes ;-).

3. Transfiere settings.php al nuevo proyecto

Copia la información de conexión a base de datos y demás configuraciones personalizadas del antiguo settings.php al nuevo proyecto. Normalmente incluirá los arrays $databases['default']['default'], $settings['hash_salt'], $settings['trusted_host_patterns'] y quizás algunas configuraciones personalizadas que hiciste. Simplemente compara ambos archivos settings.php para ver qué copiar.

Asegúrate también que $config_directories['sync'] apunte a un directorio existente. Probablemente debe estar fuera de tu webroot, donde está composer.json. Si instalaste Drupal de otra manera, podría apuntar a un archivo dentro de sites/default/files/. Verifica que el directorio definido exista y sea accesible para el usuario del servidor web.

No olvides copiar los archivos de configuración para desarrollo settings.local.php y development.services.yml al nuevo proyecto.

4. Agrega módulos adicionales al nuevo composer.json

Ahora necesitas agregar todos los módulos de tu proyecto al nuevo archivo composer.json en tu nuevo webroot.

Puedes añadirlos manualmente en composer.json o usar composer require para agregar la última versión de cada módulo a tu sitio.

4.1 Obtener la lista de módulos de tu sitio

Si no usabas Composer previamente para gestionar este sitio, tu antiguo composer.json no listará los módulos en la sección 'require'. En ese caso tendrás que hacer una lista manual de todos los módulos contribuidos.

Para eso, enumera los directorios en modules/contrib/ o modules/ de tu sitio antiguo (según configuración). En composer.json simplemente añades 'drupal/' delante del nombre de cada carpeta del módulo. Por ejemplo, modules/contrib/devel/ se convierte en drupal/devel.

Asegúrate de poner los paquetes de desarrollo como drupal/devel o drupal/kint en la sección require-dev, donde ya deberías tener webflo/drupal-core-require-dev.

4.2 Añadir módulos manualmente al composer.json

Edita composer.json en la raíz de tu nuevo proyecto (por ejemplo, /var/www/sites/new_html) y copia las listas de paquetes desde las secciones 'require' y 'require-dev' del composer.json antiguo al nuevo archivo. Si haces esto manualmente, tendrás que ocuparte de usar las versiones correctas de los módulos tú mismo.

4.3 Instalar módulos usando Composer

En lugar de añadir nombres y versiones de módulos manualmente al composer.json, también puedes ejecutar composer require drupal/<nombre_módulo> para cada módulo que necesites. Puedes añadir todos tus módulos a la vez usando composer require drupal/modulo-1 drupal/modulo-2 drupal/modulo-i. Usa composer require --dev drupal/<nombre_módulo> para añadir el módulo a require-dev.

4.4 Completar la instalación de Composer

Ejecuta composer install desde el directorio de tu proyecto (por ejemplo, /var/www/sites/new_html/). Esto descargará todos los módulos que añadiste previamente en composer.json. Si tienes problemas, elimina composer.lock y el directorio vendors y vuelve a intentarlo.

No necesitas habilitar manualmente todos los módulos porque usarás la base de datos de tu sitio antiguo o importarás esa base de datos al nuevo sitio.

5. Actualiza la base de datos y limpia la caché

Asegúrate de aplicar todas las actualizaciones de base de datos disponibles ejecutando drush updb.

Luego limpia la caché de Drupal ejecutando drush cr desde el directorio del proyecto (/var/www/sites/new_html).

Si ves el error Missing $settings['hash_salt'] in settings.php al ejecutar drush updb, consulta la sección “Solución de problemas” más abajo. Probablemente olvidaste copiar algunos valores del archivo settings.php del sitio antiguo.

6. Actualiza la configuración del servidor web

Actualiza la configuración de tu servidor web para que apunte al nuevo webroot. En nuestro ejemplo, /var/www/sites/new_html/web/. Si usas PHP-FPM, también actualiza su configuración (ej. /etc/php/7.2/fpm/pool.d/yoursite.conf) para apuntar al nuevo webroot. Recuerda reiniciar o recargar los servicios tras actualizar la configuración.

7. Solución de problemas

7.1 Advertencias o errores en la página de reportes

Revisa los reportes de tu sitio para asegurarte de que no aparezcan muchas advertencias o errores. Si seguiste esta guía sin actualizar primero tu sitio antiguo a la última versión de Drupal, probablemente actualizaste núcleo y módulos a sus últimas versiones, lo que puede causar errores o advertencias que antes no tenías. Corrígelos como lo harías tras cualquier actualización normal de Drupal.

7.2 Falta el Hash Salt

Si ves el error Missing $settings['hash_salt'] in settings.php al ejecutar drush updb o drush cr, probablemente olvidaste copiar el valor $settings['hash_salt'] de tu antiguo settings.php. Puedes copiar el hash_salt desde el archivo antiguo o generar uno nuevo ejecutando este comando en la raíz de tu sitio:

drush php-eval 'echo \Drupal\Component\Utility\Crypt::randomBytesBase64(55) . "\n"'

Esto imprimirá un nuevo valor hash que puedes copiar y pegar en tu nuevo archivo settings.php.