An overhaul of J.V. Manufacturing's corporate Intranet page.
This site combines links & services from the previous intranet site with portals to access ticket repositories from old SpiceWorks On-prem helpdesks.

Features

Quick access links for useful sites & documents
Portals accessing historical tickets from Request & Sales helpdesks
PHP rewrite of the J.V. Safety Quiz

Platform

Based on Symfony 6.3.3, a php framework for developing web applications.
It is cross-platform compatible, and can be run on Windows or Linux servers.

Install

Configuring Git

The recommended way to manage the app is through version-control software, such as Git. Git is recommended as it greatly simplifies continuous integration/development and provides a robust system for managing application versions.
This section will detail how to set up Git SCM for Windows.

Install Git

Download Git SCM for Windows
Run the installer. Default settings are acceptable.

Deployment

Requirements:

Git must be installed on the host system. See Server Setup – Install Git for instructions on installing.

Clone the repo

Open a terminal to the root of the C drive, or wherever the production code will reside.
Copy the link to this repo. This is the address to the page you're looking at now.
Use this following command to clone the repository:

git clone [the link you copied in step 2] Symfony

The tickets database is included in the clone, but attachments are not. The default and sales folders will need to be copied into Symfony/public/TicketAttachments manually. Failure to do so will result in broken attachments.
In the project root find the file .env.prod and make a copy of it. Rename the copy to .env

Look through the contents of .env and make sure these settings match your needs. Specifically, look at who will receive complaint emails

IIS Configuration

https://learn.microsoft.com/en-us/iis/application-frameworks/scenario-build-a-php-website-on-iis/configuring-step-1-install-iis-and-php
These instructions are based on Microsoft’s official documentation at the link above.

Prerequisites:

PHP 8.x.x
Composer, latest version
IIS with CGI

Installing PHP

Download PHP You need the NON-THREAD-SAFE VERSION

Create a new folder in C:/php and extract the contents of the php zip there.
In C:/php locate php.ini – production and rename it to php.ini
Add C:/php to the system PATH variable
Edit php.ini, find ;extension = php_openssl.dll and remove the semicolon
Repeat step 4 with the lines extension = php_sqlite.dll and extension = php_sqlite3.dll
Save and close php.ini

Install Composer

Download the Windows installer here
If you haven’t yet added PHP to the PATH var, then do that first. After that’s done, just run the installer and install it for all users.

Install URL Rewrite 2 for IIS

Get URL Rewrite here
Simply run the installer. IIS needs to be installed already.

Configure IIS for PHP

Open IIS Manager.

Add a new website, name it something like Intranet. Make sure Symfony gets its own Application Pool.
The physical path should route to the public folder inside the Symfony directory.
The protocol should be HTTP on port 80.
Uncheck Start Website Immediately and click OK.
In Connections select the new website and then open Handler Mappings
Under Actions click Add Module Mapping
a. Request Path should be *.php
b. Module should be set to FastCgiModule
c. Executable should be set to the path to php-cgi.exe that was bundled with your PHP install.
d. Name can be FastCGI
Back in the Connections pane select the new website again. Then open URL Rewrite
In the Actions pane, click Add Rules, under Inbound Rules select Blank rule and name the new rule File Request
a. Set the Pattern to /(.*)
b. Under Conditions, add 3 new rules
i. Change ‘Check if input string:’ to Is a File and click OK.
ii. Change ‘Check if input string:’ to Does Not Match the Pattern and set the Pattern to ‘.php’ without quotes. Enable Ignore case and click OK.
iii. Change ‘Check if input string:’ to Does Not Match the Pattern and set the Pattern to ‘.htm’ without quotes. Enable Ignore case and click OK.
c. Under Action, set Action Type to None
d. Under Action, enable Stop processing of subsequent rules
e. In Actions (on the right) click Apply and then Back to Rules
Repeat step 8, but configure the new rule as follows
a. Name: Symfony Routing
b. Pattern: /(.*)
c. Action: Rewrite
d. Rewrite URL: /Index.php
Recycle the Application Pool for the intranet website and test.
(Optional) Prepare the site cache
a. Open a terminal into the web app folder (i.e. C:/Symfony)
b. Run: php bin/console cache:warmup

Configure The App

In the project directory, you should have changed .env-prod to .env during install. This file contains our general configurations. By default, it comes preset for your environment, but double check that everything is how you want it.

Final Deployment Considerations

Make sure the IIS user (ISUR or whatever the AppPoolIdentity is) has read & write privileges within the /var directory.
Make sure Symfony is not running in DEBUG mode (APP_DEBUG should not be true in env vars.)

Updating

When new code is pushed to the remote master, it can be synchronized using a simple command:

git pull

After this is done, run Update.bat in the project directory.

So long as best practices with Git are respected, and the remote is available, the production codebase should be updated to reflect the most recent version.
If you don’t see any changes, then it’s possible that master is behind another branch containing the new code. If this is the case, you’ll need to merge that branch into master before pulling. Merging branches can get messy and complicated quickly to new Git users, so it will not be explained here. Best practice dictates no changes should ever be made directly to master so it is highly recommended to learn some Git basics before modifying any code.

Content Management

Changing page contents is mostly handled within special configuration files. Changes made to these files are reflected immediately upon saving. If you’ve chosen to deploy using Git, it’s important to know that changes made to production files may be overwritten during the next pull if they’re not committed. See the section Committing Changes for advice on persisting these.

Main page

Portal Content on the main page is generated from the portalLinks.yaml file in the %project_dir%/config folder.
The file follows the structure in which the data will be rendered on the webpage. Links are separated into objects (cards on the webpage.) Cards and links render in the order they’re given in the YAML file.

Creating Cards

Create a new line in portalLinks.yaml and indent it with 2 spaces. Type the UNIQUE title of the card and append a colon at the end. Save the file. An empty card will now be rendered when the page is loaded

Creating Links

Create a new line under the card you want the link to be contained in.
Indent the new line with 5 spaces. Add a hyphen (dash) followed by another space.
Paste this YAML onto the new line:

{ title: 'Example Link', url: '', disabled: false}

Replace the placeholder values accordingly:
a. title: The text to be displayed
b. url: the path this should link to. If internal, relative is fine. If external, use the absolute URI.
c. disabled: Optional. If included and set to true, the button will be rendered but inactive.
Save the file. The changes should be visible the next time the homepage is loaded by a client.

Message of the Day (MOTD)

The MOTD is a banner that is displayed at the top of every page. It’s great for making announcements to users, such as advising them of an issue or advertising a new feature.
The message’s contents are read from the ‘MOTD’ environment variable. Changes to this value are visible immediately.
If this value is blank, the MOTD will not be rendered.

Safety Training Documents

Just like the main portal page, content on the Safety site as well as quiz questions are generated from YAML files.

Creating Training Topics

Building the Page

Make a new file under %project_dir%/templates/Training/Safety/Topics. Name this file [name].html.twig. Filenames should be lowercase. Each html.twig file should have HTML placed between html and body tags, as you would with any other webpage.

Notice: Header and navbars are inserted by the controller during rendering. There is no need to manually add these elements.

Serving Files

Any file (such as videos) placed in the web root (%project_dir%/public) can be served to users. Symfony will automatically generate links to these files.

Place the file you want to serve in the public folder. Using a subdirectory in this location is encouraged.
In the .html.twig file, determine where you want the link and define a code block by places 2 enclosed curly-brackets. {{ }}
Inside of the brackets, type asset(‘someLinkHere.pdf’) Replace someLinkHere with the relative path to the file to serve from public

Example: video.mp4 is at ./public/videos/video.mp4

{{ asset(‘videos/video.mp4’) }}

So long as this file actually exists (and you remembered to save the .html.twig document) this code block will be replaced with a link to the file when the page is loaded.
If this file exists but a 404 error is returned, then the filename may need to be changed to something IIS can recognize. Remove spaces and unusual characters from the file name.

Adding the Link

With the page created, adding a new link is easy. Navigate to %project_dir%/config/safetyLinks.yaml and edit the file in any text editor. By default, this file is split into 3 sections, keyed by the name of the card. Figure out which card you want the new link on and make a new line under it following the example of the rest of the file.
You may copy this YAML snippet as a starting point:

    - { title: 'Link Title', url: 'somesubject', disabled: false}

title: This is what will be displayed as the text when a link is rendered
url: This should be the FIRST PART of the filename of the html.twig file. If the full filename is ‘safetyFirst.html.twig’ then this value should be ‘safetyFirst’ case-sensitive.
disabled: False by default. If set to true, the link will be rendered but will be inactionable.

Safety Quiz – Managing Questions

The YAML file for this section is at %project_dir%/config/SafetyQuiz.yaml

The Safety Quiz supports multiple-choice questions, and allows for multiple correct answers. There is no requirement for number of questions and options.

Object Structure

Each question/answer object is keyed by a unique string, such as Question_1, Q2, etc. This string does not get used by the quiz, so it doesn’t matter what this is.
Text: The question itself. This is what the tester will see.
Choices: Answer options for the question go here.
Label: The text that’s displayed to represent the selection
Value: A True/false determining if this is the correct answer or not.

Committing Changes

Changes made to production code will have to be discarded before any updates can be pulled from the upstream repository that modify those changed files. In case the production repo has to be restored, these changes will also be lost unless they’re committed and pushed upstream. In the interest of simplicity, this section will describe the process for committing changes directly to master. This goes against best practice, but will be fine for page config changes.

Open a terminal to the project root. On production, this should be C:/Symfony
Use the following commands to stage * changes, commit them, and push the changes upstream:

Command	Description
`git add [filename]`	Instructs git to track the file at the specified relative path. Wildcards may be used
`git commit -m “[Commit Message]”`	Commits changes to the current branch (likely master) with the provided message. Message should be a short description of changes. Example: ‘add sharepoint portal link’
`git pull`	Pulls pending changes from upstream. ALWAYS do this before a push
`git push`	Updates upstream origin with the changes made.

If this is your first time committing, Git will throw an error. You need to configure a name and email to commit under. Open a terminal and use the following commands.

git config --global user.name "Your Name"
git config --global user.email "Your@Email"

Reverting Changes

To restore production to the current upstream branch (undoing any changes made locally) use this command

git restore

All changes that have not been committed will be discarded.
If you need to revert something that has already been committed, that will not be covered here as it is beyond scope of this document.

README.md Unescape Escape

Overview