cornell-custom-dev / laravel-starter-kit
Cornell University Custom Development Laravel Starter Kit
Requires
- php: ^8.1
- cubear/cwd_framework_lite: ^3.0
- livewire/livewire: ^3.3
- propaganistas/laravel-phone: ^5.0
- spatie/laravel-package-tools: ^1.16
Requires (Dev)
- laravel/pint: ^1.13
- orchestra/testbench: ^8.17
- phpunit/phpunit: ^10.5
This package is auto-updated.
Last update: 2024-04-25 18:04:54 UTC
README
A Cornell University CIT Custom Development starter kit and library for Laravel.
Goals
- Reduce time to build Laravel apps
- Increase consistency in configuration, third-party packages, and architecture
- Increase code visibility, code quality, and team collaboration
- Continuously improve code and practices
- Lower barriers for support and reduce support time
Usage
The Starter Kit can be used as a starter kit for a new site or as a library for an existing site.
Starter Kit
Used as a starter kit, this package deploys the cwd_framework_lite infrastructure and standard configuration files. The steps below get from a fresh Laravel install to a working site.
-
Follow standard Laravel project creation, namely
composer create-project --no-dev laravel/laravel your-app-name
This is done with the
--no-dev
option, because we will be committing the vendor dir and don't need that extra baggage.NOTE: If you have GitHub CLI installed, you can immediately add this to GitHub as a repo with the following commands (be sure to replace the "your-app-name" references with your project info):
cd your-app-name git init git add . && git commit -m "Initial commit" git branch -m main gh repo create --private CU-CommunityApps/CD-your-app-name git push --set-upstream origin main
-
Composer require the LaravelStarterKit
composer require --update-no-dev cornell-custom-dev/laravel-starter-kit
Similar to the
create-project
option, the--update-no-dev
keeps us from adding baggage to the vendor dir. -
Install the Starter Kit
php artisan starterkit:install
This will publish
README.md
,.env.example
,.gitignore
, and.lando.yml
files to the base directory, configured on the project settings and update thecomposer.json
file to match. It will also publish HTML/CSS/JS assets from cwd_framework_lite and a set of view components that can be used to begin a layout (seeviews/cd-index.blade.php
for example usage).NOTE: The install step updates
.gitignore
so that the vendor directory is no longer excluded. The next commit will be large because it includes everything in the vendor directory.git add . && git commit -m "Starter Kit install" git push
-
Testing the site
You can confirm the site is working with Lando, since the Starter Kit install process adds a.lando.yml
file.lando start
Then visit https://your-app-name.lndo.site and you should see the default Laravel page. To see the Laravel Starter Kit example page, edit
/resources/views/welcome.blade.php
to be:@include('cd-index')
Existing Site
For an existing Laravel site, this package can be composer-required to provide the library of classes. In this case, you will not need to run the full Starter Kit install.
composer require --update-no-dev cornell-custom-dev/laravel-starter-kit
Libraries
The libraries included in the Starter Kit are documented in their respective README files:
- Contact/PhoneNumber: A library for parsing and formatting a phone number.
Deploying a site
Once a Media3 site has been created, you have confirmed you can reach the default site via a web browser, and you have access to the site login by command line, the code can be deployed.
You will likely need to map the php
command to the correct version by editing ~/.bashrc
to include this alias (for this to take effect, run source ~/.bashrc
or just log in again):
# User specific aliases and functions alias php="/usr/local/bin/ea-php81"
Since www/your-site/public
will already exist, you need to do a little moving things around to git clone your site repo from GitHub:
cd www/your-site mv public public.default git clone --bare https://github.com/CU-CommunityApps/CD-your-app-name.git .git git init && git checkout main
At this point you can configure the www/your-site/.env
file:
cp .env.example .env php artisan key:generate nano .env
Be sure to set your APP_*
values to appropriate values, based on whether it is production:
APP_NAME="Your Site" APP_ENV=production APP_DEBUG=false APP_URL=https://your-site.edu
APP_NAME="Your Site - TEST" APP_ENV=testing APP_DEBUG=true APP_URL=https://test.your-site.edu
If you visit your site now, you should see the Laravel site working.
Contributing
Anyone on the Custom Development team should be welcome and able to contribute. See CONTRIBUTING for details on how be involved and provide quality contributions.