A summary of small things a php programmer can do to improve the code and the readability of code.
estimated reading time (without links): 15 minutes
There are so brilliant programming concepts and paradigms in the PHP community. I don't want to chew them again and again. But I think everybody needs some easy small things we can improve in our everyday's work. There are so many books, conferences, videos and so on, where you can learn great new or old architectures. But most of the time you have to start from scratch or read thick books before you can start. That is fine, but IMO there are so many small things you can improve and start now. I saw many developer doing great work in general, but no one understands the goal of their software or the way to the goal. There will be the day they dont support their fancy tools any more. And a new developer starts from scratch, because he or she do not understands the code at all. Everybody can produce legacy code. (legacy code is code that works) So IMO the best code is code that everybody can understand by reading it. This repository should help to see, that there are so many small things we can improve from now on.
I am convinced that in a complex situation the small things makes the difference.
- PHP programming
- Learning the basics
- Blogs
- Tools
- IDE
- Important composer packages
- Code reviews
- Documentation
Every thesis can be an advise.
- Every advice has its own context and the context beats every advice.
- Please use common sense for every advice, because they are no rules.
- Every advice which does not bring any benefit should be skipped.
- Never create advices from subjective perspectives.
- A advice should ever have a real benefit.
- A advice should apply generally.
- You don't have to follow them all, but you should know that they exist.
- comment: You should not miss out any advice, if you dont know the reason.
These are some theses I developed in more than 10 years of programming in teams. It is just a numbered list to get in discussion about it. New thesis will be placed at the end of the list. Feel free to add some of them. The given list is farley no complete, but these points I was talking about too often and it maybe help other too.
My context has always been to develop products that have to be adapted and extended over a long period of time. Defects in these products result in direct financial loss or a blocker of work for teams.
-
What cannot be tested should not be programmed.
- comment: There are many tools for automated testing, but start with PHPUnit.
-
Use type declarations for all properties, functions (return types and parameters) and variables in your code.
- comment: They didn't come in for nothing.
-
Immutability is king.
- comment: Know the advantages.
-
Always check clauses (e.g. in IFs) with the most accurate possible value.
- comment: Return types can change, but the clause should not. (core methods can also be changed.)
-
Avoid else and try early returns.
- comment: Read some why's.
-
Do not use arrays across class (or function) boundaries.
- comment: They are not typed.
-
String concatenation always with
sprintf.- comment: It is easier to extend and it prevents magic.
-
Use yoda comparison.
- comment: Explanation. You can look at the same position for every clause and you prevent to assign a variable.
-
Use
declare(strict_types=1);at the top of every PHP script- comment: Explanation
-
Use
finalfor your objects.- comment: Our brain is not designed to understand inheritance (like exponential function).
-
The default visibility
privateapplies to properties and functions.- comment: You have to take care about every public function or property like a public api.
-
As long as annotations are not a language construct in PHP use them sparingly and only for inevitable process control or external packages where the maintainers know what they are doing.
- comment: Writing your own annotations is for pro's or use PHP8 attributes.
-
Do not use full namespaces in the code,
useeven if only\has to be specified- comment: You can see how many external dependencies your class have.
-
Traits should never use traits. I think you should prevent traits at all.
- comment: It is nearly impossible to get out of this inheritance tree. And think at exponential functions.
-
Strings should be consts.
- Try to prevent strings from your code besides output and use constants instead. They are reusable and you reduce copy-paste-errors.
-
Do not check in commented or unused code.
- comment: You have a version control system, use it.
-
No abbreviations in the code.
- comment: You use an IDE, use it.
-
Use dev-dependency-tools as phar files.
- comment: Your requirement-tree will be thankful, there are less conflicts and its faster.
-
Do not use a synchronous programming language like a asynchronous.
- comment: I know there are good approaches, but both types are different ways of thinking. Maybe it is my fault, but IMO you can make one way very good, or two a little bit.
This is just a small snapshot I can recommend.
- Principles of object oriented design (web)
- The clean coder (book | web)
- Extremely defensive PHP (video | slides)
- Design pattern (web)
- PHP standards recommendations PSR
- Semantic versioning (web)
- Refactoring (book)
- Principles of package design (book)
- A philosophy of software design (book)
- Pro git (ebook)
There are many more interesting blogs, but these selection cross up my way multiple times.
- https://blog.jetbrains.com/phpstorm/
- https://blog.cleancoder.com/
- https://matthiasnoback.nl/
- https://ocramius.github.io/
- use package managers for your local requirements
- for example in MacOS install brew
- install php over brew on MacOS
- comment: the big advantage is to have multiple versions linked by brew directly from the cellar
- install git over brew on MacOS
- install Oh My Zsh bash on MacOS
- install composer globally for dependency management in PHP
- install xdebug for debugging, tracing, profiling and the codecoverage
- use a automation server like jenkins for continuous integration, continuous deployment or any other automation
- use a remote repository server like gitlab or bitbucket or at least github
- use a private package repository like satis
- use a error tracker like sentry
- if you need regex, than use this page
- you want to schedule a cronjob, than look at this page
- you are not sure with your version constraint, than look at this page
- use an IDE for example PHPStorm
- set PHPStorm up (jetbrains documentation) correctly
- use inspections
- use one of the default codestyles in PHPStorm for example PSR-12
- use xdebug in PHPStorm (documentation)
- take a look at PHPStorm features like testing, database, deployment, version control, ...
- use plugins of PHPStorm:
- PHP Inspections - EA Extended und Ultimate
- composer
- .env
- php annotations
- auto format while save
- bash support
- select a plugin for framework support like symfony
The list of packages is not complete, but you can start projects from this stack.
- Composer package to handle Security advisories.
- Do not commit secrets and use .env's instead.
- The testing framework PHPUnit.
- If you reached nearly 100% of code coverage than you can go further with infection.
- Static code analyses with PHPStan or Psalm.
- PHP Codesniffer with PHPCS and PHPCBF.
- Dependency injection of symfony
- PHP library to generate UUIDs.
- Simple composer PHAR file handling with tooly.
- Simple Enum abstraction inspired by MySQL.
There are some packages you can install and use as global dependency.
- Run Composer1 installs parallel with prestissimo.
- Composer2 is very fast on its own. Uninstall this plugin and update the Composer itself.
Start making code reviews. If you dont know how? Read this article
You are not your Code!
- code reviewer do not comment you, they comment your code
If you find code you do not understand, ask.
- It is not the question if you should know, but when.
I only saw one approach, which seems to be suitable for software projects and this is arc42.
For further diagrams or graphs you can use draw.io.