DEV Community: SyntaxSeed (Sherri W)

RPG In A Box – A Game Dev Tool For Everyone

SyntaxSeed (Sherri W) — Mon, 19 Dec 2022 23:37:17 +0000

One recent evening, my husband grabbed my attention, to show me a newly free title on Epic Games, called RPG In A Box. On a brief read of the description I figured it sounds interesting, so he added it to his library so we can try it for free later.

Fast forward about a week, and my oldest son -10 years old- starts excitedly telling me about a game that he’s making. With a shop, and different weapons based on which class you are going to be, that he’s building inside of… Minecraft. Now, this is not very unusual. He’s had a strong interest in making games for a couple years now. From printouts and leftover minis turned into board games – my favourites being "Don’t Wake Mom!" and "AmongUs Ants: Board Game Edition". To game authoring tools aimed at children like level editors in games like Mario Brothers and Battle Block Theatre, to more recently Game Builder Garage which we own on the Switch. He’s constantly building things in these tools. He even play tests and tweaks them repeatedly to get the balance just right.

The downsides to these video game options, is that the games you create with them are trapped inside of those tools. To play one of his Game Builder Garage games, you must also own Game Builder Garage. As kid-friendly as these are, they are walled gardens and typically it’s just his brothers and us his parents who play his games. I also get the feeling that what he really wants to create is a bit beyond the scope of these tools. Custom quests and characters, big maps and the ability to tell a story.

In comes RPG In A Box. It's a game development toolkit that is very approachable. You can write simple scripts with a visual editor or dive into the code to create more complexity. It comes with a variety of editors for maps, voxel models (voxels are like pixels but 3D), combat, sound effects, quests and more. Everything is layed out well in a nicely designed interface. Every menu option and tab has an icon next to it, which aids in the friendliness. There’s detailed in-app documentation, and a full demo game that you can load up and edit, to study how it works or to use as a starting point. You can even start a fresh game but import the assets from the demo game to get you rolling.

The game lets you export your games for Windows, Linux and Mac computers, and you aren’t trapped in the RPG In a Box ecosystem. You are allowed to sell your games without royalties, and there is even a free demo version (which I started using from Steam on my Linux machine, to learn alongside my son) which has all the features, just a limited map size and a branded splash screen on exports.

My son and I have been at it for a little over a week. It’s all he wants to talk about and he’s been eagerly offering to do extra chores to earn additional computer time. We’ve been picking things up surprisingly quickly. And I’ve been quite pleased to discover that he’s been figuring out aspects of the tool that I haven’t even touch yet myself. For example he’s managed to get his game to trigger several turn-based fights with the combat editor, and we didn’t even watch a tutorial on that aspect of the tool. I really thought I’d have to help him a lot more, but he’s running with it.

Which brings me to the one criticism I have so far. RPG In a Box is new to the scene. It released version 1.0 in May 2022. And its userbase seems small so far. As a result, the amount of user-generated content like tutorials, beginners’ guides, etc are very limited. There are only a few YouTubers who’ve created videos on how to use the application. The official RPG In A Box channel has a completely fantastic tutorial series on YouTube by the creator’s wife which are 100% perfect for beginners, but unfortunately they cover the voxel editor only. If you want to go beyond map and voxel model editing, and a bit of Bauxite (the scripting language) and the very basics, you’re out of luck. There is high-quality documentation in the app and on the website, but as of this writing it’s incomplete. For example, the online docs wiki refers in several pages to quests (there is a Quest editor in the game), but the quest page on the wiki is currently empty.

It’s understandable that the rush to add new features is very real and it’s hard to justify time for documentation or tutorials when users are rabidly demanding the next feature or a critical bug fix. However in this stage of a tool’s lifetime, capturing those interested users who just need a bit of a hand-hold to really adopt your software is worth its time in gold. If I could make one suggestion to the creator, Justin, it would be to set aside a sprint or two to JUST work on documentation, and to definitely continue the tutorial series that Sarah started creating on YouTube. After the voxel editor, the tutorials don’t need to be quite so beginner friendly. A 20 minute overview of each tool in the software and also a video series on how the demo game was made, would be a great start. The game does have a very active Discord server and I’ve been receiving a lot of help there as well.

To put my money where my mouth is so to speak, I will be creating a series of posts on my blog to cover tasks I’ve figured out how to do, and useful bauxite scripts I’ve written for common tasks in RPG In a Box. Hopefully helping to make it so when users google common, problems, they find RPG In a Box specific answers. 🙂

Conclusion: I will absolutely be buying the full version soon, and probably creating a bunch of guides and maybe some YouTube tutorials myself. More documention and YouTube guides will come with time, because a tool this great and this approachable will gain passionate users like a magnet. If you’re looking for a friendly, useable game authoring tool, and especially if you’re looking for something you can use along with your older kids and teens, or for students in school, this is a great option for you.

Update, Dec 21: Another several days of actively working with the tool, including one fun day without school where my son and I bascially spent all day working with it, and I have to revise my review a bit at least for myself. I work on a Ubuntu Linux development PC, and I don’t know whether the stability issues I’m encountering are related to my environment, or RPG In a Box… however, I encounter game crashes very frequently (when I Quick Play my games, not of the application itself). I can’t add a real-time attackable NPC to the game because encountering the character crashes it. Even the demo game that comes with the software, crashes at a very specific point in the game when played.

I’ve reported a few bugs in the official Discord channel and the creator kindly reached out to say he's going to temporarily remove the offical 'supported on Linux' state and revisit in the future. Since these are pretty much show-stoppers, I’ll have to shelve the tool for now and try it again after a few more updates. I’ll definitely be coming back in the future.

All that said however, my son who is using it on a Windows 10 machine, has encountered none of these issues, and his game he’s been working on has been coming along fantastically.

TL;DR – If you’re on a Linux pc, I recommend trying the free demo first, and make sure you can play all the way through the demonstration game that’s included.

--
Originally Published on Blog.SyntaxSeed.com

Learn PHP For Experienced Developers

SyntaxSeed (Sherri W) — Mon, 11 Jan 2021 16:12:27 +0000

In my efforts to help a colleague, I discovered that there are few resources for people who are already programmers in other languages to learn PHP. Something that isn't beginner level, doesn't explain basic programming concepts... just get to the heart of what makes PHP unique, and some suggested quality resources to learn more.

This is what I've written here. It's a high-level overview of the language, and some vetted resources to get set up and learn more.

Let's get started...

Set Up A Local Dev Environment

Even if you aren't going to be using a major framework like Symfony or Laravel... if you set up an environment that can run these frameworks, you'll have everything you'll likely need for most PHP development. These usually include:

PHP – the language runtime
MySQL – database
NGINX or Apache – web server
Composer – PHP's package manager

Do you like VMs? Use the excellent Vagrant box customized for PHP development called Homestead. (I have used this myself.)

Like Docker? Try:

Have/want a local webserver?

XAMPP is one of the most popular solutions. It is a distribution of Apache with MariaDB & PHP included.

If you already have Apache or NGINX installed locally and like to do local development without a virtual machine – you can install PHP and it's most popular extensions directly. These are the commands I use on Ubuntu (Linux) to install PHP:

sudo add-apt-repository -y ppa:ondrej/php
sudo apt-get update
sudo apt install -y php7.4 php7.4-common php7.4-cli php7.4-fpm libapache2-mod-php7.4 php-pear php7.4-bcmath php7.4-bz2 php7.4-curl php7.4-dev php7.4-gd php7.4-intl php-gettext php7.4-json php7.4-mbstring php7.4-mysql php7.4-opcache php7.4-readline php7.4-soap php7.4-sqlite3 php-xdebug php7.4-xml php7.4-xmlrpc php7.4-zip

On Windows, many developers use WAMP. You can also install it directly using WSL (Windows Subsystem For Linux) or use the Windows install guide in the official PHP manual. The move to WSL2 means Windows users can more or less follow Linux guides. Laragon is another dev environment for Windows.

Users on Mac often use MAMP.

For myself, I work on a Ubuntu machine and I have PHP, MySQL & Apache installed directly.

These are some excellent guides for setting up a local environment:

Try It Out

You'll know you're ready to roll when you can run:

php -v

on a command line and see the PHP version info.

PHP has a built in command line interactive mode which lets you type and run PHP commands to try things out. Type:

php -a

It will give you a prompt where you can enter lines of PHP code and when you hit enter it will run those lines and show the output. If you like using something like this, I recommend the more advanced PsySH which does the same thing but much nicer.

You can run a PHP file from the command line like so:

php index.php

PHP also has a built-in web server that you can use instead of having Apache or NGINX installed. This is nice for quick testing. In fact much of my development uses this built in web server and a local installation of MySQL. I have Apache but often don't need it. Run the built-in web server within a directory that has .php files like so:

php -S localhost:8000

This will start up the web server listening on the given host and port. Then if you visit http://localhost:8000/ in your browser you can execute your PHP application that exists in that directory.

Note that the index.php file is the entry point for most PHP applications. The URL above will call index.php by default.

PHP Language Overview

PHP is an interpreted language meaning that your PHP programs are not compiled ahead of time. When a browser makes a request to a web server for a PHP resource (usually a .php file) the web server provides all the details of the request (for example the URL GET parameters, POST values, cookies, headers, etc) to the PHP interpreter which executes the requested PHP file. If you edit a PHP file on the server, that change will take place immediately.

Most of the time the index.php file is the entry point to a PHP application and it usually performs some bootstrapping and executes the framework to handle the request values which are often packaged together into a Request object. Older applications might not use a Request object, in that case the values from the request can be found in $_GET, $_POST, $_COOKIE, $_SERVER super global arrays which are accessible from anywhere in an application. Modern frameworks place these into a Request object then wipe out those super global values to prevent pitfalls of global variables.

As the PHP program executes, the output is returned to the browser. Some programs send output in an ad hoc manner using echo() statements and similar commands which send output to the standard output stream (back to the web server which sends it to the browser... or to the command line). Modern applications gather all output into a Response object which is sent to the browser all at once at the end of the program's execution (one of the framework's final steps).

PHP is stateless by default. All variables, objects, and connections created when the program executes for a request, are not retained for the next request. PHP clears the memory used during that request and doesn't know anything between one request to the next. Multiple requests coming into a server can be executed concurrently.

There are mechanisms that PHP developers use to maintain some memory or state between requests. The most common method is Sessions. PHP sends the browser a session ID value which is usually stored in a cookie. The browser sends back this ID with all future requests. PHP uses that ID to look up values stored on the filesystem or in a database (or a data store like Redis or Memcached) that are associated with that ID. In this way PHP can ‘remember' the visitor between requests. However these values in the Session storage must be read from the data store on every request. They are saved in a super global called $_SESSION which can be accessed from within the application. Many frameworks place this super global into their own Session object.

This is a good article (https://carlalexander.ca/php-application/) about how PHP works including topics about concurrency and multitasking in PHP.

Types In PHP

PHP is a dynamic, weakly typed language. Variables are not defined with a type (and cannot be), instead the type is inferred by what is assigned to it and can change if something new is assigned.

$something = 1;  // Weakly typed as an integer.
$something = "Hello";  // Now it's a string.

This means that you will find a lot of type checking and casting in PHP programs:

$age = intval($age);  // Make sure $age is an integer.

if( is_int($age) ){
    // Do something.
}

The above sorts of forcing and checking of types are very common in PHP applications. Since all values passed to PHP in the request from the browser are strings, PHP programs will often cast these values to the types expected.

In recent years, PHP has added strict typing features. This means function and method parameters can explicitly set a type for the incoming parameters and return types. A runtime exception will be thrown if the incoming value is not the expected type. If you see this directive:

declare(strict_types=1);

At the top of a file, then the types in that file will be treated as strict. This means that type strictness in files may differ. This enables large applications to migrate to strict types one file at a time.

For example:

declare(strict_types=1);

function doSomething(int $id): string {
    $id = '' . $id;
    // This is allowed in PHP: $id is a string now.
}

doSomething('1'); // This would trigger a TypeError.
doSomething(1);   // This would be fine.

A ? in front of a type means that value is nullable (it can also be null).

PHP's type system can be a source of confusion or errors. Code should be highly aware of what type a variable is at any given time and that it can change. Many people recommend the use of strict types where possible.

More info about types in PHP:

PHP Arrays – Learn To Love Them

One of the most common types of data structure in PHP is arrays. PHP developers use arrays for all kinds of things – often in place of data objects which might not be the best idea! Arrays in PHP are very flexible because they are actually hashmaps. This means the array key does not have to be sequential or even numeric. Filling an array with disconnected integer indexes does not mean that all the array cells between will be reserved:

$houses[0] = 'Blue';
$houses[55] = 'Red';
printf( array_key_exists(8, $houses) ); // 0 (false)

Array keys can be strings:

$config['username'] = 'tonystark';
$config['password'] = 'ironman123';

// This can also be defined like so:

$config = ['username' => 'tonystark', 'password' => 'ironman123'];

You can also declare a value as an empty array ahead of time, or you can assign many values which will be given sequential, numeric keys starting at 0:

$superheros = array(); // empty array.

$superheros = array('Superman', 'Batman', 'Black Widow', 'Ironman');
print_r($superheros); // [0] => Superman, [1] => Batman ...etc

All of the keys in a PHP array don't even have to be the same type! PHP.net has a lot of documentation about arrays and PHP provides many built in functions for sorting and manipulating arrays.

PHP Syntax

PHP's syntax is slightly related to C. Some highlights:

All variables begin with a $. Class names, method and function names do not.
All statements end with a ;.
Control structures are wrapped in curly braces {}.
White space and indenting does not matter.
PHP code begins with <?php (sometimes just <? for short) and ends with a ?>. This code can be interspersed in regular HTML... but modern applications don't do that anymore. If a file ends with PHP code, the closing tag is left off.
Strings can be wrapped in single or double quotes. Special characters (like \n for a newline) will only be recognized in double quotes.
Many projects have a coding standards guide or loose policy to keep things consistent. For example, class names begin with a capital.

This article gives a quick overview of PHP syntax:

My beloved PHP cheat sheet

Eric The Coder ・ Dec 17 '20

#php #laravel #beginners

Code Analysis

The PHP community has created many excellent tools which enable you to perform analysis on the style, quality, and even correctness of your PHP code. These static analysis tools can be valuable to help keep your projects on a set coding style, or to find code smells in your application. While there are many PHP analysis tools to choose from, some popular ones are:

Autoloading and Composer

If your PHP application entry point is the index.php file... no other files of source code will be run or referenced unless they are included into the requested file. So if you run a file “test.php”, only the code in that file will be available. Historically projects would use several include or require statements to bring other code in:

<?php
// File index.php

require('config.php'); // Execution will stop if this file is not found.
include('functions.php'); // If the file isn't found, execution continues anyway.
require_once('user.php'); // Ensure this isn't included multiple times.

$foo = 'bar';

You may see many includes like the above at the top of an index.php file which will bring in class definitions, functions, etc which are needed by the application.

Modern PHP applications don't use includes like this anymore. Composer is the package manager for PHP. It also provides an autoloader which will include class (object definition) files automatically, only once they are needed by the application. This prevents including code that is never used. Composer when configured in a project creates a vendor/ directory where it will place the autoloader and any installed packages. If you see a vendor directory or a composer.json file at the root of a project, that's how you can tell that Composer is being used. Don't be surprised if many older applications don't use it. PEAR is an older system used to install packages into PHP projects.

In the case of Composer autoloading being used, you will see this at the top of every file in an application:

require_once 'vendor/autoload.php';

Composer lets us pull in dependencies (like the open source projects found on Packagist) and they will be installed in the vendor directory and become instantly available to our projects. We can pin them to certain version numbers, update our dependencies and declare some packages to be for the dev environment only (like testing and static analysis tools).

Understanding and learning Composer is very relevant for modern PHP development. An intro to Composer is found here: https://getcomposer.org/doc/00-intro.md.

PHP Resources & Looking Ahead

PHP is a very old language and the tutorials, StackOverflow answers, and blog posts about PHP that you might find online can be very outdated and include many security flaws. I recommend not using resources or code from over 3 years ago.

PHP's versions have a defined lifecycle. Make sure you are using a supported version.

PHP has some of the best official documentation around, including examples and user-contributed comments. The official docs are found at https://www.php.net/.

The official publication (magazine) for PHP is php[architect]. I've had a subscription for several years and sometimes write for the magazine. A lot of high-quality targeted information in here.

One of the top resources for learning modern PHP is the website https://phptherightway.com/.

The following is a large list of useful resources:

https://odan.github.io/learn-php/.

The website https://laracasts.com/ is full of very high quality PHP and web development tutorials. Many are specific to the Laravel framework, but there are also many that cover PHP in general and modern best practises. I love this resource so much, that despite not using Laravel, I have a lifetime subscription to LaraCasts. Suggested series:

There is a similar screencasts website for the other top PHP framework, Symfony (the one I use) found at https://symfonycasts.com/.

The most popular editors for PHP are VSCode (what I use) & SublimeText. If you prefer a full IDE, the best is PHPStorm, but it is a commercial product.

Enjoy Your Journey

Today, PHP is a modern, flexible, popular programming language. The community is very large and welcoming, and the wealth of resources about PHP is vast and varied. I enjoy using PHP and the language continues to receive core updates and new versions which just keep getting better. PHP 8 was released very recently. Welcome to PHP and thanks for reading!

--
Originally Published on Blog.SyntaxSeed.com

DarkLang Intro And First Impressions

SyntaxSeed (Sherri W) — Fri, 08 Jan 2021 16:14:56 +0000

A colleague mentioned a new language and serverless environment called Dark (or DarkLang if you don't want a zillion unrelated search results). It sounded interesting so I created an account to check it out.

What Is DarkLang?

Dark is a language, environment, online editor and serverless deployment infrastructure to create and serve backends for your applications. It lends itself well to APIs, bots and even CRUD applications. There's nothing to set up on your machine, everything is done online in your Dark account. Everything you write in their online editor is instantly deployed and consumable.

How To Get Started

Dark is currently in Beta but they are open for new signups. I created an account on their website https://darklang.com/ and was instantly brought into the online editor to write my first endpoint with a 2 minute tutorial.

The guided tutorial helped me create a basic GET endpoint and return a Hello World result. When this was complete it provided a link to open a more complex CRUD example application.

Ellen, one of the founders of Dark, has a great introduction YouTube video which I watched after creating this hello world example.

From here, Dark has a much more in depth Your First App tutorial which will be my next learning step.

First Impressions

I'm very intrigued by the absolutely minimal barrier to entry here. No editor or software to install, no dev environment to set up, nothing to run or configure, no deployment. I created an API endpoint with utterly zero fuss. Awesome!

As cool as that is, it brings to mind some questions.

How do I prevent myself from developing directly in production with all the risks that entails?
How do I control when a new update becomes live? I saw brief mentions of feature flags, but couldn't readily see how to use them.
Will there be mechanisms for testing my applications?
How do I have my own backups of my Dark programs? It seems like if Dark goes down or ratchets up prices, then I'm stuck.
What even is or will be Dark's pricing model? I'd like to know what I'm getting into.
How well will Dark scale?
Version control or collaboration? This seems designed for only one developer to work on a project with no way to roll back changes.
What if I don't want to use the Dark online editor?
Committing to Dark seems to be the highest level of trust you'd ever have to place on a tool or service, since you don't have control of literally any part of your Dark applications.

Other Feedback

At first blush the online editor is snappy, fast and pretty cool. However it lacks many convenience features like the ability to resize the blocks you create to change how long lines will wrap. There seems to be no way to enter blank lines to make your code readable. And comments are just a special kind of variable declaration which makes it so they don't stand out.

Account management is still very Beta. You can't delete your unwanted canvases, rename them or duplicate them if you want to try something out. You can't configure your account profile or even change your name, email and password as far as I can see.

If I was one of the founders of Dark, I would change all my marketing to name this DarkLang not Dark. Anyone googling for future development questions about Dark will never get specific search results because the word 'dark' is so generic and will also bring up articles that mention 'dark mode'. Naming this just 'dark' will make it much harder to promote and use.

Dark has a product roadmap that mentions some of these concerns.

Ideas For Uses

Create mock APIs for testing my applications written in other languages.
Fast creation of SlackBots and similar.
Glue to join two or more other APIs together.
Provide a wrapper for isolating or extending 3rd party APIs.
Rapid development of demos and proofs of concept.
API solution for mobile app development.

Conclusion

For me... I think I will file this under: "Looks really cool and has potential, but needs to mature. Check it out again in a year". :D

--
Originally Published on Blog.SyntaxSeed.com

Let's Talk About: Coercive Software Design

SyntaxSeed (Sherri W) — Thu, 29 Oct 2020 19:30:13 +0000

We become developers with the understanding that our mission with the software we create is to meet the needs of users. But what happens when the software we create is being used to change or coerce the behaviour of users, rather than help them work, play and behave the way they want to? What are the ethical considerations of developing software that tries to manipulate users? Where does the profit-driven motivation go too far?

Coercive: using force to persuade people to do things that they are unwilling to do. (Cambridge Dictionary)

I recently started thinking about this topic, when Facebook pushed out new changes that cut off my last method of checking my messages on my phone. I refuse to install the Messenger app, and instead I primarily use Facebook in the Chrome/Brave mobile browser on my phone. Facebook began as a website. I have always used it this way.

A couple years ago they released an update that would tell me to download the Messenger app to view my messages. Since then I could turn on 'Desktop Mode' in my browser and still access my messages. In a broken layout with a horizontal scrollbar, but it was at least usable. Today, even Desktop Mode doesn't work. I get this:

In theory I could find a mobile browser that lets me spoof the useragent and try that... but using a different browser would disrupt all my other activities on my phone, and I can't even be sure that would work - they were closing that loophole a few years ago. I've decided to stop trying to force Facebook to let me use it, and just stop using Facebook so much.

Let's talk about this for a moment.

Facebook spent considerable time drawing all of us in. Making themselves the de facto method of connecting with our friends and family. Few people in my circles call, text or email each other anymore. They use FB messages. Facebook became a necessary default in our lives, and they are now coercing me into their app riddled with privacy issues, onto my older phone with limited space for more apps.

Facebook isn't even trying to meet my needs as a user. If I need to check the messages for my business page, I can still do so on my phone. So the code for the mobile messenger website is there.

This type of coercive behaviour is everywhere now.

If I visit many websites from my phone - Twitter, Reddit, Facebook, etc I get a popup that offers their mobile app. I can usually choose "Get The App" or "Not Now". There is never, ever, a "Don't ask me again" option. I'm nagged by these popups everywhere.

Notification Hell

One of many reasons I refuse to install social apps, is the bombardment of notifications and 'unread' indicators that are all over my digital experience these days. Those tiny read circles with numbers indicating messages I've yet to check. I disable these whenever I can, but they are still everywhere. Designed intentionally to press your buttons to make you clear them. I don't have my email push to my phone for this reason.

I want to control when I'm notified about unread emails. I want to decide when I'm willing to work or be reachable, and when I'm not.

Coercion Examples

I've seen other examples of software and websites trying to force my use of them in one way or another, often in ways that are detrimental to my user experience. For example:

Opting me into the most invasive privacy or marketing settings by default.
Burying important options down several layers deep in the settings.
Intentionally hiding phone numbers or email addresses from a company's support page, even though these exist.
Delivering notifications in a staggered asynchronous way so that even once you've 'cleared' all your notifications, more appear even if they are from hours before you last cleared them all.
Intentionally making features unavailable on the web version and limiting it to app users.
Unethical billing practises such as opting users into auto-renew subscriptions without their consent. Ignoring cancellation requests.
Disguising buttons to encourage accident clicks. The Amazon Prime signup button is a good example of this.

Conclusion

This is a topic I've just begun to think about, so I don't have a lot to say about what we as developers should be doing about this topic. Do we just take the approach that "well Facebook is free so you can't complain"? Does that even apply if I don't even have the choice to pay and use it how I want?

Do we as developers have the power, or the desire to push back against these practises?

I know that I have decided to step back from my use of Facebook over this issue, but it is a steep price to pay, since I'll lose out on a lot of connections. And even if I choose to take this stance, none of my friends or family care enough about privacy to make the same decision.

What do you think about it fellow developers? And what other examples of this behaviour have you seen?

--
Originally Published on Blog.SyntaxSeed.com

Combating Phone Addiction: Try, Fail & Try Again

SyntaxSeed (Sherri W) — Thu, 19 Dec 2019 15:43:56 +0000

Let me preface this by saying that this post discusses my own experiences and observations in my life. Your perspective may vary, and what works for me or is a problem for me, may not be so in your life. That's ok, we're all different and awesome.

My husband and I are on round 4 (ish) of our attempts to renew our resolutions to find a healthier balance of our phone and online use. As a web developer it's tempting to almost live online, but at least for us, that's a fast track to unhappiness. Luckily it hasn't been an extreme problem- it hasn't interfered with our careers or parenting or physical health. But there have definitely been some concequences of too much phone use.

For me it's social media, tutorials and articles, and an endless stream of screencasts and videos of conference talks. It used to be mobile browser games too. It's fluffy amateur fiction and lots of Twitter. For my husband it was games, then YouTube videos, news (often not even about our own country), Reddit and comedy specials. Our phones are endless sources of dopamine shots and minimally interesting or entertaining material.

This temptation catches us on our phones during the commercials when watching a broadcast TV show. In the washroom, or on the couch while the children play around us like that heartbreaking Papaoutai video {French}.

To clarify - my kids do not want for loving, affectionate and involved parenting. I'm a work-from-home parent until September and my kids are snuggled and given heaps of attention. What's missing is getting down on the floor and playing games like pretend and checkers and the like, more often than we do now.

Some of the things I know have been a consequence of too much phone use:

I read WAY fewer books than I used to.
I have less time for non-online hobbies.
Less time for meaningful board and video gaming.
We go outside less, to just play in the neighbourhood or yard.
Less frequent playing with my kids.
Less meaningful learning cemented with putting what I learn into use.
Almost zero time spent bored or daydreaming.

You know what? Each of the things I'd rather be doing require a tiny modicum of energy more than just reaching for our phones. They require a longer attention span too. Our attention spans are another muscle we've noticed has atrophied like our tolerance for boredom, or our capacity for unguided imaginative thought. And we humans are masters of finding the path of least resistance.

So, we fight this battle. Set limits. Fall off the wagon. And get back on.

Our latest round of limits:

No phones in the washroom. It's like a force field keeping them out of there. Bring a book.
A limited block of free browsing each day.
If we need to use our phone - for work, or looking things up, it happens in the kitchen - the least comfortable room.
No phones on the couches or when watching a show together.
If I want to read a bunch of articles, or a screencast, it happens at my computer when I'm in 'work mode' and can practise along or make notes.
We continue to make use of a DNS filtering service to block distracting sites at certain times of day.

We also re-established a weekly schedule, blocking our evenings into a balance of time for work, relaxation, and side-projects. This helps us to feel like we are never lacking in time for the things we want and need to do. Time for each other, time to be productive, and time for relaxing fun. Thursdays are also family board game night. Wednesdays are date night - even if that's just watching a show then playing some co-op video games. This is a system we have used in the past to much benefit, we just fell out of the routine lately. We try to plan fun/R&R (Rest & Relaxation) nights on our most exhausting days when work or kids' after school activities make the days feel long.

We have 3 R&R nights each week. 3 nights for work or side-projects. And one 'flex' night to use as needed or plan social outings. This type of scheduling isn't for everyone. But it helps us feel like we have a balance. No guilt on fun nights that we should be working. And less resistance to work nights because we know we have plenty of relax time.

An additional resolution - also exacerbated by too much phone use, is our tendency to go to bed too late. When you have kids, that precious kid-free time in the evening is gold. But staying up too late is robbing from ourselves tomorrow. So an addition to our phone limits and schedule are strict bedtimes that will help us feel fresher and less frazzled the next day.

As I write this, it's now 3 days into our renewed efforts. It's not easy. The temptation and FOMO (Fear Of Missing Out) is real. In our conversations with friends and colleagues we know that we aren't alone in these struggles. I hope that this post can be a way to reach out to others and share our story. Find out what works for others. And hold ourselves accountable.

What's been your experience in this area? Any tips that work for you? Do you have other resolutions that are top of mind as we head into the new year? You can do it!

--
Originally Published on Blog.SyntaxSeed.com

Photo by Marjan Grabowski

Legacy PHP Application: PHP Code Sniffer Compatibility Standard

SyntaxSeed (Sherri W) — Wed, 20 Nov 2019 17:03:55 +0000

Part 1 of this series covers a tour of my 14+ year old legacy CMS called LampLight and it continues with my use of command line code analysis tools to migrate it from PHP v 5.6 to 7.3. In this part I'll use PHP_CodeSniffer to check my applications compatibility with PHP v 7.3 and beyond.

Let's not fuss around, and instead dive right into the meat of this post. At the root of my project I run:

phpcs --standard=PHPCompatibility --extensions=php,inc,lib -s --runtime-set testVersion 7.3- .

Hot damn it's not too bad! A couple pages of errors flagged, mostly boiling down to these two:

Line Ending Madness

Good grief, I can't seem to escape this mixed line endings issue. It's been flagged and fixed repeatedly. Opening the file in VSCode, reveals down in the bottom right corner an indicator of CRLF meaning Windows style endings. I want everything to use Linux style endings (LF), I work on a Linux machine, this shouldn't be complicated. Unfortunately a lot of my old code was written on Windows.

The odd thing is that PHP_CodeSniffer didn't even flag all the files that were problematic. I suppose it's only noticing files where there are both types of endings.

At this point I ran through several attempts to fix it using tools like dos2unix and other scripts off of StackOverflow, my usual git reset tricks, and more. It was an hour-long tangent and nothing seemed to work.

I discovered that most of these tools, including Git's methods, can convert files with consistent line endings... but once a file has MIXED endings, they aren't automatically converted. Though I can't figure out why my fixers weren't doing it. UG.

Ultimately I ended up opening every single file in VSCode and manually select-all and convert to LF endings. It took me about 10 minutes which is way less time than I spent researching it. I'm now fairly certain that all text files use LF line endings. (Knock on wood.)

Running the PHP_CodeSniffer command again and... AAARRRGGGH! It's flagging one file as still having mixed line endings. Opening it in VSCode indicates LF endings. Using my bash cat command replacement bat on the file, shows mixed endings indeed.

So in VSCode I select all and convert to CRLF and then back again to LF endings. Drum roll... hallelujah PHP_CodeSniffer no longer reporting mixed line ending issues. VSCode is lacking in this area. It needs a 'mixed' indicator.

Let's move on to the real issues that PHP_CodeSniffer revealed.

Farewell get_magic_quotes_gpc()

Well, well, I'll try not to blush as I write this, but PHP_CodeSniffer is flagging a few uses of get_magic_quotes_gpc() in my code. A dig into the PHP docs reveals that this oft-maligned feature of PHP was removed as of PHP 5.4.0! So, this is clearly a hold-over of some very, very, very old code. Let's look at what it's doing:

function stripSlashesDeep($value)
{
    $value = is_array($value) ? array_map('stripSlashesDeep', $value) : stripslashes($value);
    return $value;
}
if (get_magic_quotes_gpc()) {
    $_GET    = stripSlashesDeep($_GET);
    $_POST   = stripSlashesDeep($_POST);
    $_COOKIE = stripSlashesDeep($_COOKIE);
}

This first instance is in my bootstrap file and is just cleaning the automatically inserted slashes from the request globals. I'll just remove this completely.

The final instance of magic quotes is in a string escaping method in my database class/facade which wraps the mysqli functions.

public function escapeStr($inStr, $stripSlashes=false)
    {
        $this->connect(); // If not already connected.

        if ($stripSlashes) {            
            if (get_magic_quotes_gpc()) {
                $inStr = stripslashes($inStr);                
            }
        }

        $inStr = mysqli_real_escape_string($this->dbc, $inStr);
        return $inStr;
    }

Since it's no longer needed I'll just remove the section resulting in:

public function escapeStr($inStr, $stripSlashes=false)
    {
        $this->connect(); // If not already connected.
        $inStr = mysqli_real_escape_string($this->dbc, $inStr);
        return $inStr;
    }

Now is a good time for a test of the application and a git commit. What's next?

Indirect Access Ambiguity

The final error says:

Indirect access to variables, properties and methods will be evaluated strictly in left-to-right order since PHP 7.0. Use curly braces to remove ambiguity.

This error is flagged in two spots. Let's look at the code:

$$_SERVER["SERVER_NAME"] = $oldservername;

Well, well how embarrassing. This is actually a typo and the two dollar signs shouldn't be there. Easy enough to fix. The other instance is the same.

Had this been a real use of variable variable names, or indirect access to variables... we can use curly braces to specify how to evaluate it. For example:

$$whichVar = "New value";

Becomes:

${$whichVar} = "New value";

With this issue fixed, let's commit to Git, then run the command one more time to verify that this PHP_CodeSniffer isn't finding anything else with this compatibility check. Great!

Migration Wrap Up

One of the most difficult parts of this migration process is that none of my older projects have automated tests of any kind. This exercise has really driven home why I need them and cemented my existing determination to create tests with all future projects. That said however, it has been surprisingly easy to migrate each individual project, with the help of these excellent tools. The main challenge is the sheer number of projects I have to migrate, and my limited time to allocate to this process.

In summary, here are the CLI tools I've been using:

Can be safely run automatically:

php-cs-fixer fix . --rules=full_opening_tag,no_closing_tag,@PSR1,@PSR2 --verbose --dry-run --using-cache=no

php-cs-fixer fix . --rules=@PHP70Migration,@PHP71Migration,@PHP73Migration --verbose --dry-run --using-cache=no

Should probably do manually:

php-cs-fixer fix . --rules=@PHP70Migration:risky,@PHP71Migration:risky,-declare_strict_types,-void_return --verbose --dry-run --using-cache=no --allow-risky=yes

phpcs --standard=PHPCompatibility --extensions=php,inc,lib --runtime-set testVersion 7.3- .

Plus:

Clean out commented out or dead code.
Remove abandoned tiny projects and proof of concepts that are lying around inside other projects.
Organize project structure.
Get it running on my local dev environment.
Fix obvious issues like the use of __autoload() and count().
Migrate Mercurial to Git.
Full manual test on PHP v 7.3.

It would be a great idea to integrate these types of checks into your Continuous Integration process, or at least in a pre-push or pre-commit Git hook to help keep these issues from sneaking back in. Especially style issues that aren't caught by tests. This is something I'm in the process of doing myself.

I hope this series was helpful, and has given you a starting point for migrating legacy PHP projects, using command line analysis tools, and trusting automated fixer to tidy and correct your code.

Thanks for reading!

--
Originally Published on Blog.SyntaxSeed.com

Legacy PHP Application: PHP CS Fixer & PHP Code Sniffer for PSR1 & PSR2

SyntaxSeed (Sherri W) — Tue, 05 Nov 2019 00:02:00 +0000

Part 1 of this series covers a tour of my 14+ year old legacy CMS called LampLight and it continues with my use of command line code analysis tools to migrate it from PHP v 5.6 to 7.3. In this part we'll continue to use PHP CS Fixer to clean up the code, and will then move on to use PHP Code Sniffer for even more tidying.

My last few uses of PHP Coding Standards Fixer, are to check for PSR1 and PSR2 compliance. These PSRs cover a baseline of code style conventions common among PHP projects.

Note that PHP CS Fixer provides rulesets for these PSRs, but they do not cover ALL of the rules found in the PSRs. For now I'll just start with these, since it's an easy process and a discontinued project.

First, running the ruleset for PSR1:

php-cs-fixer fix . --rules=@PSR1 --verbose --using-cache=no --dry-run

Actually reveals no issues! This is because I fixed the line ending problem when I migrated this project from Mercurial to Git. And the opening tags issue was solved in part 1 of this series. Well that was easy. So on to PSR2:

PHP CS Fixer and PSR2

php-cs-fixer fix . --rules=@PSR2 --verbose --using-cache=no --dry-run

This run however, reveals a TON of problems, in almost every file! Eeek!

There's no way I want to either automatically fix this many issues at once, or try to pick my way through each one. So, I'll use this output to pick out one rule at a time and run only that. Look it up to see what's involved and if it looks straightforward I'll let the fixer do it's thing and then test. When I'm happy I'll git commit to checkpoint my changes. This way I'll work my way through all the rules covered by the @PSR2 ruleset.

You'll notice that many of these rules deal with how whitespace is handled. This means there is very little risk in letting the fixer correct these automatically.

This process worked well and problem-free for each of these rules:

no_trailing_whitespace
no_trailing_whitespace_in_comment
single_blank_line_at_eof
indentation_type
method_argument_space
braces
function_declaration
no_spaces_inside_parenthesis
no_spaces_after_function_name
line_ending
lowercase_keywords
lowercase_constants

And these were all of the PSR2 rules that were flagged for my project. Turns out that I had no issues with any of these, and could have run the entire ruleset automatically.

One odd thing that kept creeping up is that the line endings kept having to be re-fixed on several files. Not sure what went on there. But it seems to have finally stayed fixed.

For the purposes of this project, this is it for what I wanted to do with PHP CS Fixer. Let's move on to another awesome tool for PHP code analysis.

PHP Code Sniffer

PHP Code Sniffer aka PHP_CodeSniffer is another command line tool you can use to analyze your code based on various standards. On my legacy applications like this one, it flags a TON of issues. For this case, I'm only interested in checking for problems with the current version of PHP or future deprecations.

This is where the PHPCompatibility standard for PHP_CodeSniffer comes into play. But first, just for fun, let's see if PHP_CodeSniffer picks up any PSR2 violations that PHP CS Fixer missed. Use the -s flag to make sure that each error also indicates which sniff was violated.

phpcs --standard=PSR2 -s .

Woah! This tool finds many things not covered by PHP CS Fixer! From the output we can see that all items marked with an [x] can be fixed automatically if we change to the bundled tool phpcbf. In my terminal PHP_CodeSniffer has reported pages upon pages of violations. Here are just a few:

We can break down which 'sniffs' are in a given standard with the following command:

phpcs --standard=PSR2 -e

Using this list, I can run PHP_CodeSniffer on a single rule or 'sniff'. And begin to break down that giant list of violations into only the ones I want to fix. Here's the spaces instead of tabs one:

phpcs --sniffs=Generic.WhiteSpace.DisallowTabIndent -s .

The included tool PHP Code Beautifier and Fixer aka Phpcbf can be used to fix these automatically. In most cases just replace the command name and it will work. First I'll git commit my work up to now and give it a try:

phpcbf --sniffs=Generic.WhiteSpace.DisallowTabIndent .

Wow, this fixed 77 files for me! I'll do the same routine with only the few things I want PHP_CodeSniffer to deal with. I could spend way more time on this given how many errors PHP_CodeSniffer found, but again this is a discontinued project and I don't want to spend too much time. So I limit my fixes to:

phpcbf --sniffs=Generic.WhiteSpace.DisallowTabIndent .

phpcbf --sniffs=Generic.Functions.FunctionCallArgumentSpacing .

phpcbf --standard=Squiz --sniffs=Squiz.Functions.FunctionDeclarationArgumentSpacing .

A few gotchas popped up during this process. To fix a specific sniff you must also specify the standard that sniff is found in. Also, in your output with the -s flag, you'll see it says something like:

Squiz.Functions.FunctionDeclarationArgumentSpacing.SpaceBeforeEquals

But the last part of this is a rule inside of the sniff. So I had to remove the .SpaceBeforeEquals part to make sure it matches the actual containing sniff.

This process required frequent reference to the output of phpcs --standard=PSR2 -e, which I eventually just ran in another terminal panel.

After a few of these individual sniffs were fixed I was losing track of where I was in relation to what PHP_CodeSniffer originally found. I wanted a more high-level view of what PHP_CodeSniffer is finding. To do so, I can specify a different report type:

phpcs --standard=PSR2 --report=source -s .

Oy. I have to admit that at this stage of the process, the thought of tracking down each of these sniffs and fixing each one and testing it... just didn't seem worth it to me for rules that are largely stylistic in nature and for a discontinued project. So this is where I stopped with the PSR2 checks with PHP_CodeSniffer. I think this gives you, dear reader, enough of a handle on how to use this tool for these types of fixes.

I get the impression that PHP_CodeSniffer is more powerful than PHP CS Fixer for these style-based PSR checks.

What I really want to do, is address issues that actually affect my application running on PHP version 7.3 (and future versions). So in the next part of this series, I'll move on to using PHP_CodeSniffer to run sniffs in the PHPCompatibility standard, which will find real issues that need to be addressed.

--
Originally Published on Blog.SyntaxSeed.com

Legacy PHP Application: Code Analysis With PHP CS Fixer

SyntaxSeed (Sherri W) — Fri, 25 Oct 2019 15:57:23 +0000

In part one of this series we took a tour into my 14+ year old legacy CMS called LampLight. It's an oldie but a goodie and it needs some love because it's still in use by a couple clients and myself. We are migrating it from PHP v 5.6 to 7.3. In this part we'll use PHP CS Fixer to identify problems and clean things up.

PHP Short Tags and Closing Tags

Talk has been cheap for some time regarding the deprecation of the short opening tag <? for PHP, and its removal has had a few false starts. Finally, a PSR for this change has passed and it will officially be deprecated in v 7.4.

We also want to eliminate the closing PHP tag in files that contain only PHP. These two issues are quite straightforward, so let's use these as an easy dip-of-the-toe into using command line code analysis tools to have a look at our code. We can even use these tools to make the changes for us.

I first commit all my work to my Git repo and push it to the remote.

We'll use PHP Coding Standards Fixer aka php-cs-fixer for this. It's a powerful tool to analyze code issues and fix them for you. At the root of my CMS project I run:

php-cs-fixer fix . --rules=full_opening_tag,no_closing_tag --verbose --dry-run --using-cache=no

I rarely use the cache because I don't want it creating files in my project, and I use the --dry-run flag to see what the output would be before actually doing anything. You can also use the --diff flag to see what would be changed by the fixer in a diff format. You can see the only rules I'm running are for short tags and closing tag removal. This gives me a list of all the files which have a problem, and at the top a nice visual summary which looks like this for only one rule:

All the green 'F's represent files that will be fixed. The dots are files with no fixes. That's a lot! I'm confident this is an easy fix that I trust to be done automatically so I remove the --dry-run flag and run the command again.

Now it's fixed my files for me. So easy! I do a full test of my application then commit the changes to Git. Not bad for 5 minutes on a Wednesday. And we are now familiar with PHP CS Fixer. A handy tool for every PHP developer's belt.

PHP Version Compatibility

PHP CS Fixer has a lot of fixes available. Let's look them up. Visit the PHP CS Fixer Configurator Rules site to look up the available rules and rulesets. You may have to update the fixer and/or install additional rules.

Ah ha! There are rules for checking PHP version compatibility. I'm most interested in the migration rule SETS (preceded by an @ symbol):

@PHP70Migration and @PHP70Migration:risky
@PHP71Migration and @PHP71Migration:risky
@PHP73Migration

For some reason there doesn't seem to be a ruleset for 7.2. Oh well, let's use what we have.

One by one we will run the fixer with a rule set. First with the --dry-run flag. You could technically do all the rulesets at once by comma separating them... but I don't like to have to wade through a zillion problems at once.

The sets labelled 'risky' should sometimes be fixed by hand instead of trusting the fixer to do them. You can look at the reasons why it's risky in the rule info in the Configurator and decide for yourself. Let's do the first non-risky one:

php-cs-fixer fix . --rules=@PHP70Migration --verbose --dry-run --using-cache=no

Miraculously no problems reported! The risky rule next (note the additional --allow-risky=yes flag), and I make sure it's only a dry-run:

php-cs-fixer fix . --rules=@PHP70Migration:risky --verbose --dry-run --using-cache=no --allow-risky=yes

Woah! A ton of issues, mostly for the declare_strict_types rule. Let's look that rule up in the Configurator site. Yup just like it sounds, it tries to force a strict types declaration at the top of the file. I don't want to do that, so can I add a rule exception to my ruleset? YES! Just add it to the rules list starting with a minus:

php-cs-fixer fix . --rules=@PHP70Migration:risky,-declare_strict_types --verbose --dry-run --using-cache=no --allow-risky=yes

Much better, only a few issues, exclusively from the random_api_migration rule. We need to use the proper random functions. I'll go into each file and fix them up manually. Test and then git commit.

A 'Random' Gotcha

When I first tried to manually fix the random_api_migration rule, I changed all instances of rand() to mt_rand(). PHP CS Fixer kept flagging the same errors, even though I was doing the change via the examples in the Configurator docs. I spent too much time thinking the fixer was still using a cache. Gave up and ran the fixer without the dry-run flag. Lo and behold it changed these instances to random_int() instead of mt_rand(). So the Configurator docs are wrong, and this is the recommended way to generate random integers.

It's these kinds of surprises that keep this from being a straightforward process. On to the rules for 7.1.

Property and Method Visibility

Running the non-risky rules for PHP 7.1 is up next. Same as before but the ruleset is @PHP71Migration.

This flags only one rule violation: visibility_required which tells me class properties and methods must have visibility declared. I'm going to take the easy road here and just let them all be defaulted to public because any that should be private or protected are already declared as such. So I'll let the fixer do it for me and remove the dry-run flag.

My smoke-test reveals a new deprecation error appearing in the application:

Deprecated: Methods with the same name as their class will not be constructors in a future version of PHP; cBase has a deprecated constructor. I'll go in and fix this to a proper constructor.

Onward to the risky ruleset for 7.1.

Void Return Types

php-cs-fixer fix . --rules=@PHP71Migration:risky,-declare_strict_types --verbose --dry-run --using-cache=no --allow-risky=yes

This time we get quite a few pages flagged for the rule void_return. Looking this up in the Configurator shows that it's a suggestion to add a void return type to methods and functions if not already specified.

Return types are optional in PHP, and this application is discontinued anyway. I've decided to just leave the return types out. It's interesting to note however, if you wanted to execute this fix, PHP CS Fixer will actually check into the functions and methods to see if there are any non-empty return statements before adding the void return type. So the fixer is doing some intelligent analysis before just changing things on you.

Heredoc

php-cs-fixer fix . --rules=@PHP73Migration --verbose --using-cache=no --dry-run

This next rule set again flagged only one issue. I'm getting lucky here. The heredoc_indentation rule was complaining about 3 files. This would have been an easy fix had I just let the fixer do it. But I tried to fix it manually so that I could also learn what I was doing wrong. Well that led me down a rabbit hole of trying to fathom what the fixer was complaining about.

It turns out that it didn't like it if my heredoc text was indented more than 4 spaces beyond the line that begins the string. This seems to be a style choice enforced by the fixer. And doesn't allow me to indent it under the assignment operator (=) like I prefer.

There is no 'risky' ruleset for 7.3.

Manual Look at 7.2

Since there was no ruleset for 7.2. I'll have a look at the PHP documentation for 7.2 and see if anything catches my eye. I'm looking specifically at backward incompatible or deprecation changes.

There are quite a few gotchas in these lists. Things like the create_function() and each() functions being deprecated, and a bunch of other things. Searched my codebase for a few of these, and didn't find anything. The only real concern is that the count() function no longer accepts a value that isn't countable. I use this function everywhere, and don't do an is_countable() check before hand. I assume my values I'm passing to it are always going to be set, but this is a prime example of when a testsuite for this project would be super useful. I'm going to have to just hope that my manual test covers everything (not likely). I'll monitor the error logs just in case.

Section Wrap Up

If you wish to run ALL of the rules that we covered in this section, here is a command with everything combined:

php-cs-fixer fix . --rules=full_opening_tag,no_closing_tag,@PHP70Migration,@PHP71Migration,@PHP70Migration:risky,@PHP71Migration:risky,@PHP73Migration --verbose --dry-run --using-cache=no --allow-risky:yes

If you want to fix them one at a time, you can add the --stop-on-violation flag to the command.

The migration rules for PHP CS Fixer are not 100% exhaustive. But they are a helpful tool to cover many of your bases. I still do a read through of all the backward incompatible and deprecation changes in all the versions between 5.6 and 7.3, and scan my codebase for them.

In my next post I'll talk about using the fixer for checking PSR1 and 2 compliance. We'll then look at using PHP Code Sniffer (phpcs) to do even more code analysis.

--
Originally Published on Blog.SyntaxSeed.com

Legacy PHP Application Tour & Upgrade

SyntaxSeed (Sherri W) — Wed, 23 Oct 2019 19:27:36 +0000

The process of migrating my applications from PHP 5.6 -> 7.3 has been a long one – mainly due to limited time to work on it, and additional tasks being added to the migration list. But I’ve finally made it through the low hanging fruit of easy client sites and am now migrating the first project with a significant amount of back end PHP code. In this case, it’s a legacy CMS I wrote 14+ years ago called LampLight Content Manager.

I wrote LampLight back when WordPress was still a bit complex for some of my customers, and it was also a time of frequent security issues and hacked sites bogging down the WP ecosystem. Today it’s a much different beast and my new projects which need a CMS default to WordPress.

Anyway check out this beauty:

LampLight Content Manager. Circa 2005.

The buttons along the top represent toggle-able modules such as Articles, Gallery, Polls, etc, that I could enable or disable based on the client’s needs. I had HTML pages ready to drop into the website that could load static articles or a list of them. The editor bar inserts BBCodes because this pre-dates robust rich text editors that I liked enough. Something that less tech-savvy customers could use without creating a nested html mess and didn’t generate garbage markup.

All in all LampLight has served me well. A couple clients are still using it, and my own company website is still eating this dogfood so to speak. It’s held up well over time, and even received a dashboard design refresh along with a theme switcher several years ago. But LampLight was built for PHP 5.3 and then migrated ages ago to 5.6. And there it sat until today. Let’s have a look deeper and go through my migration process! We’ll clean it up, get it working locally for the first time and migrate to PHP 7.3. (To clarify, this is still a discontinued project, but I need to keep it working for my clients still using it.) Oddly I’m still a bit proud of this piece of software. Nothing else I’ve written has been so useful, stable, or generated so many sales. I’ll be sad to see it go.

Code Overview

The code is a mix of object oriented and procedural. There’s no auto-loading just a few includes. Configuration is pretty organized and there are feature toggles for modules. The front end uses an earlier version of my TemplateSeed PHP view library. Markup is mostly XHTML and styles use CSS, though at the time I didn’t know how to configure paths properly in CSS image URLs so the CSS file is PHP. Yikes.

I use function libraries and custom plugins to reuse code. Even today, adding features is quite simple because everything is vanilla PHP.

It uses a MySQL database for storage and I have a db class which wraps the mysqli functions for at least a small layer of abstraction. Database migrations are non-existent, just a big SQL file to initialize the database. I write my queries in raw SQL but all parameters are properly escaped with built in SQL escape functions. This is how we did it back then kids!

Deployments are just a copy of the files via SFTP to a staging server for testing and review by the client. Then SFTP again to live. SQL changes were versioned so when I promoted a new version I would run the SQL alter table queries for that version. I can’t recall this ever biting me… I was veeeery careful.

I have never had this application working on my local development machine. I would FTP changes to a hidden sub-directory and use that to preview my changes. This meant I got really good at writing a lot of code before having to actually see what it does. I’ve struggled with what I think is my ISP throttling FTP traffic and in the evenings it’s super slow, so I do a lot of writing code without many previews. The good news though, is that part of the process this week is getting it working locally – yay for instant results!

Now, enough of a tour, let’s get to work!

Step 1: Run It Locally

I created a new private Git repo and copied all the site files into it from their old home in Mercurial at BitBucket. I didn’t bother migrating the history this time because I’m breaking it out of a repo that contains several small personal sites, and re-organizing things so decided to go for a fresh start.

Moved all the actual public site files into a public/ directory, cd in there and run it via the built in PHP webserver. And voila!! A ton of errors!

Working my way through, I made several small fixes to get at least the homepage and a cursory click through to be error free:

Create a local MySQL database and set up the tables.
Create copies of my config files – rename them config-PRODUCTION.php and edit the originals for localhost.
Replace absolute paths in the configs with something along the lines of: define("DOC_ROOT", dirname(__FILE__)."/");
Replace the deprecated __autoload() function with spl_autoload_register().

Step 2: Pretty URLs without Mod_Rewrite

The first real issue, was that using the built in PHP webserver means that my .htaccess file is not used and therefore my mod_rewrite rules to handle pretty URLs are not executed. On an Apache webserver this is used (.htaccess):

RewriteEngine On

# Test that the URL isn't pointing to a real dir or file:
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d

# It's a pretty url, so rewrite index.php/URL to the url get param:
RewriteRule ^(.*)$ index.php?url=$1 [PT,L]

Using the built in PHP webserver means that the url GET parameter is never set. So my bootstraping step now needs to check if it’s empty and try to use the PATH_INFO server variable:

// Grab our passed URL parameters.
$url = $_GET['url'] ?? $_SERVER['PATH_INFO'] ?? "";
$url = ltrim($url, '/');

$urlArray = array();
$urlArray = explode("/", trim($url) );

A few more small adjustments and it works! It’s running on localhost, pulling data from the local database, and I can even log into LampLight.

But I’m running PHP 7.3 locally! Why isn’t it blowing up?

Step 3: PHP 7 Errors

Other than the __autoload() problem, the only other real issue is a few uses of count() on null or non countable input. These were trivial to fix mainly by checking for null first. And that was mainly it! Apparently this project isn’t too fancy and it sticks to very core language features.

That isn’t to say that I’m done though. The code is still a mess, and hasn’t been tested beyond a cursory click through. And sadly no, I don’t have a test-suite for this project. So in the next post, I’ll get into the meat of this process by using some code analysis tools to clean things up and identify errors.

This should be fun, see you next time!

--
Originally Published on Blog.SyntaxSeed.com

Decision Time: PHP Framework Dilemma

SyntaxSeed (Sherri W) — Wed, 11 Sep 2019 17:56:53 +0000

My freelance business has grown, and reached a critical decision point for my future development. I've been puzzling over this for a while - why not puzzle it out in public!?

I need to pick a PHP framework. Or maybe not pick one. But my dilemma is kind of unusual. I'd love the opinions of other experienced PHP devs! But hear me out, my situation is a bit unique.

Unhelpful Metrics

Extensive research has given me endless comparisons of Laravel vs Symfony & others, using completely useless (to me) metrics like:

Number of GitHub stars.
Google search popularity.
Job postings.
Number of StackOverflow questions.
Millisecond differences in speed.
Etc.

These comparisons aren't helpful. Let me explain why.

My Situation

I build websites & web applications for small to medium sized businesses. Most start as a basic website with a contact form, Google Map, and that's it. Many never grow past this. Some eventually add custom dynamic elements. Say a work-order status page. A searchable directory, etc. A few have grown bigger.

But, and this is key... I also provide hosting, so ongoing maintenance is on me. I don't deliver a project & wash my hands of it. I make future text changes, fix bugs, add things & keep it running - for sometimes many, many years. My oldest PHP project in production is over 10 years old!

Over time I will end up with DOZENS of these projects to take care of.

I don't have the luxury of one, beautiful application to keep front-of-mind.

And so, stability over time is a key. Easy upgrades are key. This is why WordPress replaced my internal CMS for clients who fit that use-case: one-click upgrades baby! That's gold.

Until recently I was using a simple, custom MVC framework that I built. Most of my existing projects are on that. But it's over 8 years old, pre-Composer, and time for a new direction. To give that old workhorse some credit though- it has needed almost zero updates over that time (likely due to stagnating on PHP v 5.6).

I have a few months of experience & learning with Laravel, it's nice. But ongoing updates are a concern. Backward compatibility isn't a priority for Laravel. And it's overkill for 90% of what I do.

I've built a few things with SlimPHP.

I'm intrigued by Symfony because it starts as a micro-framework & grows with you. Awesome!

I'm also considering sticking a few stable Composer packages together for a light version of a 'framework' that will cover all but my few large projects. Maybe Slim is exactly that?

Maybe 90% of what I do doesn't need a framework at all.

It all boils down to not wanting to regret my choice 10 years from now. My youngest child starts school next year & when that happens I'll be throwing my efforts into my business full time. Between now & then I want my ducks in a row & to do the necessary learning.

TL;DR - My Priorities

PHP based.
Stability over time.
Well documented & clear upgrade process.
Grows with my needs over time.
Doesn't break backward compatibility on a whim.
Ok to have one option for small stuff and one for big projects.

Thoughts?

Do you have experience maintaining several framework-based projects over time? What do you use? Is it painful?

Am I crazy for thinking everything even needs a framework?

How does your company handle the time spent maintaining & upgrading a client's project? Do you bill them for the time? Offer a Support Licence with a monthly fee that covers this type of work? Bundle it in the hosting fee?

Thanks everyone!

--
Originally Published on Blog.SyntaxSeed.com

Migrating Mercurial Repos To Git

SyntaxSeed (Sherri W) — Fri, 06 Sep 2019 15:31:01 +0000

In August 2019, BitBucket - a popular cloud source code hosting and project management service run by Atlassian - announced that it was dropping support for Mercurial repositories. Mercurial is a distributed source control management tool similar to, but less popular than Git.

This move isn't surprising. Mercurial has lost the popularity war with Git and BitBucket claims that less than 1% of new repositories on their service use Mercurial. The surprising thing is that BitBucket announced that they are deleting Mercurial repositories from their service as of June 2020. Leaving developers and companies who use Mercurial with less than one year to migrate.

This move by BitBucket seems inevitable, but the timeline and hard-deletion that BitBucket is giving their loyal customers seems harsh. For me, I have around 25 projects that need to be migrated.

Here's how to do so, in a few easy steps!

1. Decide Where To Go

Options abound! If you want to keep your repos on Mercurial, then you do have other hosting options including SourceHug, SourceForge, CodeBase and more. The Mercurial website has a full list of options for Mercurial hosting.

You might want to give serious thought to switching to Git.
Detailed Git tutorials are everywhere online and learning the basics is not too hard. For me, I was already learning and using Git, so this transition was a no-brainer. Since I'm unhappy with BitBucket in general, and this new issue doesn't help, I've decided to move my projects away from BitBucket. At this time I'm keeping my Open Source projects on GitHub, and my private projects will be on GitLab.

For the purposes of this tutorial, I'll be teaching you how to switch to Git.

2. Create A New Git Repo

First, using the tools on the cloud service where you will host your Git repos, create a new empty repo. Don't initialize it with a README file if that option is offered. Give some thought to how you want to organize and name your projects because this can be a pain to change later. Some services let you sort repos into groups, projects, or workspaces. Now is a good time to think about how you'll want to sort them when you have a ton of projects in the future. Don't just put them all in the root group.

Make note of the SSL url to the repo. For GitLab this looks like:

git@gitlab.com:username/repo-name.git

3. Install Fast Export

There is an awesome tool called Fast Export for converting Mercurial repositories to Git. Create a directory on your development machine where you want to install Fast Export. Such as /home/tools/fast-export/. From a terminal in that directory, clone the Fast Export tool with:

git clone https://github.com/frej/fast-export.git .

Note: If you are using Mercurial version < 4.6 and you get a "revsymbol not found" error, either update Mercurial, or use an older version of Fast Export by running this in the fast-export directory: git checkout tags/v180317

4. Prepare New Local Repo

Create a local directory where you will keep the new Git repo we are going to create with Fast Export. Initialize a new Git repo in there. Note that terminal commands may vary if you are on Windows.

mkdir /home/repos/git/my-project/
cd $_
git init

5. Use Fast Export to Convert

First make sure you have all the latest changes pulled into your local copy of the Mercurial repo. Then, from inside the newly initialized Git directory:

/home/tools/fast-export/hg-fast-export.sh -r /home/repos/mercurial/my-project/

This runs the fast export shell script on the Mercurial repo. You'll see some nice output from Fast Export that looks like:

Next, checkout the HEAD commit like so:

git checkout HEAD

When it's done, make sure to look at the hidden files and remove any Mercurial specific ones like .hgignore.

6. Connect To Remote

Connect the local Git repo to your new cloud hosted Git repo by setting the upstream SSH URL that you made note of earlier. In my case this looks like:

git remote add origin git@gitlab.com:username/repo-name.git

If you haven't already, set up an SSH Key for connecting to your hosting service. I strongly recommend this over username/password authentication. GitLab's documentation on SSH Keys is very complete.

7. Push The New Repo To The Remote Repository

Push the local Git repo to the remote. If you put a password on your SSH Key (recommended) then you will be prompted for it. To make sure you get everything up there, do:

git push -u origin --all
git push -u origin --tags

When these are done, visit the remote repo on GitLab or whichever service you chose, via your web browser. Confirm that the code and commit history is there. You may want to make a small local edit, then commit and push it to test it's all working.

These steps should work for a straightforward Mercurial repository. If you have branch names that don't convert to Git, or if you want the author information converted, there are ways to do this, just check out the Fast Export Documentation.

Bonus! Fix Line Endings

If like me, you received a bunch of warnings that your project has Windows style line endings (CRLF) and that Git was replacing them with Linux style endings (LF), you might want to ensure your local copy has the proper endings too. Many of my projects were originally created on a Windows machine but I now work on Linux, so these mixed endings have been everywhere. To make sure your local matches the remote, you can reset your local to what's now in Git. First make sure everything is pushed to the remote successfully, then do:

git rm --cached -r .
git reset --hard

This removes everything locally and then resets your working tree to the last commit. You'll lose the exiting working tree and staging area. If no commit is specified, then HEAD is assumed. Make sure your editor is using the correct line endings.

Wrap Up

That's it! Once you get this process down, migrating a Mercurial repo can take as little as 10 minutes. It's a good idea if you're new to Git, to create a sandbox repository where you can experiment and try out Git's commands. Many people like to use a GUI interface for Git as well.

For me, it is a fond farewell to Mercurial. It has served me well over 10+ years of development and I'll miss its simplicity. ❤

Good Luck with your own migration!

--
Originally Published on Blog.SyntaxSeed.com

Multiple Apps on One Server With Mod-Rewrite

SyntaxSeed (Sherri W) — Thu, 20 Jun 2019 14:18:53 +0000

For small companies and freelance or solo developers, hosting can be an expense which adds up over time to a hefty bill. Whether you have several VPSes or shared-hosting accounts, it makes little sense to have multiple small, experimental, or low-traffic sites on their own servers. You could serve them from multiple subdomains or subdirectories, but yuck! Domains are cheap and I like the polish of having something on it's own domain once it's public.

However, hosting companies usually only give you one web root directory. In the case of a VPS, sometimes provisioning them charges a small fee per 'app'. An app being a distinct project or site on it's own domain and with a separate web root directory (such as /www/appname/html/).

Fake It Till You Make It

Let's look at how we can use Apache's mod-rewrite module to create several fake web roots and send traffic to them based on request domain.

Setup

First, we'll assume that you already have one domain (such as example.com) pointed to your server. It is serving pages that you place in your web root.

Next, park a second domain (example.net) to the same server or hosting account. I won't get into how domain parking works. This second domain should be serving the same pages in the same web root like an alias. Two domains to a single site.

Then in your web root, create two directories:

site-examplecom/
site-examplenet/

And move your existing site files into the first one. Add a placeholder index.html with some text to the second one, so we will see when one or the other site is served. Now you're ready for the magic.

Mod Rewrite Is A Multi-tool Of Awesome

Apache HTTP Server has a module called Mod_Rewrite which is usually installed by default. Make sure you have it on your server. You can give Apache instructions via a .htaccess file in your web root. These will affect the directory the file is in, and all subdirectories. Create an empty file named .htaccess in your web root, or edit the existing one. Don't put it in those site-* directories we created earlier.

Next, put the following in that file and we'll look at what it does.

<IfModule mod_rewrite.c>
RewriteEngine On

# Direct requests for example.COM:
RewriteCond %{HTTP_HOST} ^(?:www\.)?example\.com
RewriteCond %{REQUEST_URI} !^/site-examplecom/
RewriteRule ^(.*)$ /site-examplecom/$1 [L]

# Direct requests for example.NET:
RewriteCond %{HTTP_HOST} ^(?:www\.)?example\.net
RewriteCond %{REQUEST_URI} !^/site-examplenet
RewriteRule ^(.*)$ /site-examplenet/$1 [L]

</IfModule>

Mod_Rewrite takes the requested URL, and based on PCRE regular expression rules, can change the corresponding filesystem path or even rewrite to a different URL.

The <IfModule> directive will ensure that the lines inside are only executed if that module exists.

The first line inside is clear, it turns on the rewrite engine. No kidding.

Then we have two nearly identical blocks of 3 lines led by a comment. Let's examine those 3 lines.

First:

RewriteCond %{HTTP_HOST} ^(?:www\.)?example\.com

One or more RewriteCond directives can precede a RewriteRule. The rule will only be executed if the preceding conditions are met.

This line compares the incoming http host from the request headers (base domain part of the URL) to the regular expression ^(?:www\.)?example\.com. The ^ symbol means 'starts with'. So we are checking if the request host begins with example.com with the www. being optional and not captured to a variable. If it the host matches this regex, we move onto the next line.

Second:

RewriteCond %{REQUEST_URI} !^/site-examplecom

This condition checks if the request URI (the part after the host/domain) does NOT (the '!' negates the regex) start with /site-examplecom. Which it will contain when we do a successful rewrite. This is important, it stops us from entering an infinite loop of doom and getting a Server 500 error.

Third:

RewriteRule ^(.*)$ /site-examplecom/$1 [L]

And finally, if the conditions were met, we perform a substitution of the requested path (url part after the host and port). Watch out: the already mapped directories are removed. So if the .htaccess file is in the top web root you get the full URL path without the leading slash. If the .htaccess file was in a test/ sub directory of the web root, you'd only be matching the pattern against the part of the URL path after test/.

The (.*) pattern grabs everything from the beginning ('^') to the end ('$') of the URL path, saves it in the variable $1, then sticks it after /site-examplecom/. The [L] flag means to stop processing rules for this request if this one was executed.

High-Level Look

We have this block of two conditions and one rule, duplicated for our two 'apps'. This is the process:

If it's the right http host.
And if it's not already requesting our fake site-* app root.
Then append site-example*/ to the front of the URL path.

And that's it. You should now see the two different sites if you visit the different domains. You can add another parked domain, subdirectory and block of rewrite directives to add another 'app'.

Considerations

Faking web roots has some drawbacks. Your apps are not isolated from one another. In theory they could mess with each other, and a vulnerability in one affects the others.
Your host might have terms against doing this. Though I don't see why you wouldn't be able to harness the power of the tools at your disposal.
You should keep your applications' databases separate. This will make moving and migrating apps/sites easier, and avoid collisions with tables.
Make sure that any of your code that deals with filesystem paths, takes into account that the url path and filesystem path won't match.
Using .htaccess files slows Apache down a little bit. If you have access to the main httpd configuration for the server, you should set these rules in a <directory> block there instead.
Multiple sites on one server or hosting account can eat up system resources quickly. This is why I only recommend this for small projects with very low traffic. Sites that don't warrant their own server/hosting yet.

Fun Extras

There is an excellent tool for testing Mod_Rewrite rules found on the madewithlove website.

If you'd like to strip the www off of requests and ensure that your site is only visited via the naked domain, add this (applies to all domains) before your other rules (the R=301 flag tells browsers and search engines that this is a permanent redirect, consider leaving it off till you're happy that it's working):

# Remove the www:
RewriteCond %{HTTP_HOST} ^www\.
RewriteRule ^(.*)$ https://%{HTTP_HOST}/$1 [R=301,L]

That's All Folks

I hope this little tutorial was helpful. I learned a lot writing it, and while I've been using this for many years, I'm also curious whether anyone has any gotchas I should consider or improvements I could make. Thanks for reading!

--
Originally Published on Blog.SyntaxSeed.com