utexas / utdk_localdev
Docksal-based local development tooling for the UT Drupal Kit.
Installs: 147
Dependents: 0
Suggesters: 0
Security: 0
Stars: 2
Watchers: 4
Forks: 0
Type:utexas-development
Requires
- brianium/paratest: ^6.2
- drupal/coder: ^8.3
- drupal/devel: ^4.0
- drupal/drupal-extension: ^4.1
- drupal/entity_browser: ^2.0
- drupal/page_manager: ^4.0
- drupal/restui: ^1.0
- drush-ops/behat-drush-endpoint: ^9
- drush/drush: ~10
- friendsoftwig/twigcs: ^3.2
- jcalderonzumba/mink-phantomjs-driver: ^0.3.1
- mglaman/drupal-check: ^1.1
- mikey179/vfsstream: ^1.6
- oomphinc/composer-installers-extender: ^2
- phpspec/prophecy-phpunit: ^2.0
- phpunit/phpunit: ^8.4.1 || ^9
- squizlabs/php_codesniffer: 3.*
- symfony/phpunit-bridge: ^5.0
README
This repository contains Docksal-based tooling for internal development of the UT Drupal Kit. It should not be used for local development with an individual Drupal Kit site.
For local development on an individual Drupal Kit site, use one of the options listed at https://drupalkit.its.utexas.edu/docs/getting_started/local_development.html
For ITS
Getting started
- Make sure you have Docksal installed
- Make sure you have a recent version of PHP as your active native php-cli version. If using a Mac with Homebrew, you can do this with https://github.com/shivammathur/homebrew-php
- From the root of where you have cloned the repo, run
fin init
. This will initiate the containers. - You can then use
fin init-site
to install Drupal. - If you need to re-install the site, run
fin init-site
as needed without restarting the stack or re-running any ofsetup.sh
. - You can run
fin uli
to do adrush uli
with the appropriate URI automatically piped in to give you a valid link for admin login.
Special note: Firefox
If you use Firefox, you will need to install mkcert
in order for the browser to recognize locally-generated SSL certificates. Run the following:
brew install mkcert
brew install nss
mkcert -install
Running tests
- For first time setup, run
fin test-init
. This will copy over the default files from the.docksal/drupal/testing-defaults
folder, and update them to match your current Docksal virtual host. - Before running tests confirm the checkbox in Docker settings > Features in development (tab) > Use Rosetta for x86/amd64 emulation on Apple Silicon is checked and the "Apply and restart" button has been clicked. (and confirm the "Virutalization Framework" is enabled as per the help text)
- There are 5 commands to run testing:
run-tests
: run the entire UTexas suite of tests using parallel testingtest <directory/file>
: run PHPUnit Functional tests in series, using standard PHP command parameterstest-js <directory/file>
: run PHPUnit FunctionalJS tests in series, using standard PHP command parametersparatest-functional <directory/file>
: run PHPUnit Functional tests in parallel, using standard PHP command parametersparatest-js <directory/file>
: run PHPUnit FunctionalJS tests in parallel, using standard PHP command parameters
- More details on the commands can be found in the command files themselves -
.docksal/commands/test
and.docksal/commands/test-js
. They both function largely the same way, but are configured to use correspondingphpunit.xml
files located in.docksal/drupal/testing
folder. - To ensure proper functionality, the
SIMPLETEST_BASE_URL
has to be updated to match the Docksal virtual host name. In most cases, this is taken care of when runningfin test-init
. As part of this command, it will update the appropriatephpunit.xml
files automatically. This does a basic find and replace operation via perl, replacing the defaultweb
string with the Docksal variable${VIRTUAL_HOST}
. - If the command doesn't work for you for some reason, you can manually update the
SIMPLETEST_BASE_URL
in the includedphpunit.xml
andphpunit-js.xml
, located in.docksal/drupal/testing/
. In Docksal, the name of your host matches the name of your folder. So, if you cloned this into a folder calleddrupalin
, your Docksal based URL will behttp://drupalin.docksal
, and this is what yourSIMPLETEST_BASE_URL
should be set to.
Deprecation checking
Run the following command to run Drupal 9 compatibility checks with drupal-check:
vendor/bin/drupal-check path/to/directory
Deprecation fixes via Drupal Rector
Run the following commands to attempt to automate Drupal 9 compatibility fixes with drupal-rector
- Add the configuration file to the project root
cp vendor/palantirnet/drupal-rector/rector-config-web-dir.yml rector.yml
- Analyze the code
vendor/bin/rector process web/modules/contrib/[YOUR_MODULE] --dry-run
- Apply suggested changes
vendor/bin/rector process web/modules/contrib/[YOUR_MODULE]
Setting different versions of PHP
- The
docksal.env
file contains some sample definitions of the different pieces of the stack.WEB_IMAGE
,DB_IMAGE
, andCLI_IMAGE
can be modified to use different Docker images from the Docksal repo. The PHP version is determined from theCLI_IMAGE
. You can modify the value to a new version, and runfin up
to refresh the containers. Docksal will detect the changes, download the new Docker image if it doesn't exist in your cache, and reload your container running the new PHP version. So for example, to run on PHP 7.3, you could update theCLI_IMAGE
to beCLI_IMAGE='docksal/cli:2.6-php7.3'
, and runfin up
, and now the CLI container is running on PHP 7.3. And to clarify, the CLI container is determining what version of PHP that Drupal will be using, since Drupal is in essence running on this container, in orchestration with theWEB_IMAGE
andDB_IMAGE
containers, which are networked together automatically behind the scenes. See more information about this from the Docksal site.
Accessing database through PhpMyAdmin
- You can access PhpMyAdmin by navigating to
http://pma.{YOUR_DOCKSAL_SITE}
, replacing{YOUR_DOCKSAL_SITE}
with whatever the site URL is.
Accessing database through SequelPro
- If you have SequelPro installed, you can run
fin sequelpro
from the docroot of the site, and it will open up the database in SequelPro!
Accessing MailHog
- You can access MailHog by navigating to
http://mail.{YOUR_DOCKSAL_SITE}
, replacing{YOUR_DOCKSAL_SITE}
with whatever the site URL is.
Overriding PHP / MySQL settings
- It's possible to override PHP settings as needed. Some examples are included in the
example-php-mysql-overrides
folder. - Docksal will look for PHP overrides in
.docksal/etc/php
- for more in depth information, see the Docksal documentation - Docksal will look for MySQL overrides in
.docksal/etc/mysql
- for more in depth information, see the Docksal documentation
XDebug
This should provide "out of the box" xdebugging ability Test steps:
- Add
XDEBUG_ENABLED=1
to yourdocksal-local.env
, and do afin up
to reload the containers with XDebug enabled. If you haven't already setup aphp.ini
, add one, or update/etc/php/php.ini
settings with desired XDebug preferences (see.docksal/example-php-mysql-overrides/etc/php/php.ini
), and do afin project restart
to apply the new settings. NOTE: HavingXDEBUG_ENABLED=1
will slow down performance, so consider setting back to0
and runningfin up
to unload it if not actively using. - Download VSCode debug extension
- Go to the "debug" tab and start debugging:
- When you refresh the site in a spot where that code executes, it should jump you into vscode
Note on composer.json requirements
- Due to a current limitation with our composer scaffolding, any package that is not the root package will not have it's
require-dev
dependencies installed. Because we use the utexas_profile as a package, therequire-dev
packages defined there won't be installed, since theutexas_profile
is not the root package. That is why we duplicate them in this repo asrequirements
, so that when this package is installed, it takes care of properly installing dependencies for testing and other dev specific activities.