Celem tej serii jest rozpoczęcie głębszego zanurzenia się w pracy z programowaniem obiektowym w kontekście WordPressa.
A ponieważ API WordPress Widgets jest jednym z interfejsów API, które wykorzystuje praktyki zorientowane obiektowo, jest to logiczne miejsce na początek. Co więcej, da nam kilka podstawowych technik, które możemy zastosować w przyszłej pracy, gdy zobaczymy, jak budować więcej projektów obiektowych na WordPressie w przyszłych seriach.
Do tej pory omówiliśmy następujące kwestie:
- Widżety WordPress: podejście obiektowe. Widgets API zapewnia solidny test lakmusowy i przykład, jak rozpocząć programowanie obiektowe w WordPressie.
- Widżety WordPress: Jak wykryć programowanie obiektowe. Celem jest uzbroić Cię we wszystko, czego potrzebujesz do wykrywania praktyk zorientowanych obiektowo.
Jeśli nie nadążasz, teraz jest na to świetna pora. A jeśli tak, to pamiętasz z ostatniego postu, zakończyliśmy następującą notatką:
Oznacza to, że ponownie odwiedzimy WordPress Widget Boilerplate i zamierzam dokonać refaktoryzacji go w obecnym stanie, aby przyjąć bardziej nowoczesne standardy PHP.
Aby rozpocząć aktualizację WordPress Widget Boilerplate zgodnie ze wspomnianymi standardami, musimy zrobić kilka rzeczy:
- stworzyć gałąź z istniejącego boilerplate’u,
- zainstalować narzędzia jakości kodu,
- upewnić się, że nasze IDE jest poprawnie skonfigurowane,
- i rozpocznij refaktoryzację kodu do wspomnianych standardów.
I to właśnie zamierzamy zacząć robić w tym poście.
Zaczynając od standardów
Jeśli jesteś członkiem tej witryny od jakiegoś czasu, wiesz, że wolę używać Visual Studio Code. Jeśli nie, mam cały zestaw artykułów poświęconych temu, jak go używam (i tym samym, jak będziemy go używać w tej serii postów).
A jeśli jesteś zainteresowany omówieniem standardów kodowania, debugowania, środowisk IDE, środowisk programistycznych itd., sprawdź The Independent WordPress Developer.
Zakładam jednak, że jeśli to czytasz, to przeczytałeś powyższy materiał lub czujesz się komfortowo, przeglądając cały powyższy materiał.
Powiedziawszy to, zacznijmy.
Pobieranie repozytorium
Pierwszą rzeczą, którą będziesz chciał zrobić, to sklonować kopię repozytorium. Wolę to zrobić za pomocą wiersza poleceń.
Ponadto uważam, że warto to zrobić w stosunku do najnowszej wersji WordPressa. Jeśli nie masz kopii głównej kopii WordPressa Subversion, możesz przeczytać, jak to skonfigurować tutaj; jest to jednak całkowicie opcjonalne. Możesz śledzić resztę tego samouczka z dowolną wersją WordPressa, którą chcesz.
Aby to zrobić,
- Upewnij się, że jesteś w katalogu wtyczek swojej instalacji WordPress
- A następnie wprowadź następujące polecenia do kopii swojego terminala
$ Spowoduje to utworzenie katalogu WordPress-Widget-Boilerplate w twoim katalogu wtyczek. Możesz do niego przejść, wpisując:
$ cd WordPress-Widget-BoilerplateWyniki klonowania repozytorium powinny wyglądać mniej więcej tak:
Następnie upewnij się, że przechodzisz na gałąź deweloperską, którą utworzyłem. To naprawdę łatwe. Ale zanim to zrobimy, dlaczego nie skonfigurować projektu w Visual Studio?
Konfigurowanie kodu programu Visual Studio
Kroki konfigurowania projektu w Visual Studio Code są proste:
- Przeciągnij katalog Boilerplate do IDE,
- Otwórz zintegrowany terminal,
- Zamień gałęzie
Tak jak zrobiłem powyżej, przedstawię screencast, jak to wszystko zrobić. Przeciąganie katalogu do Visual Studio Code powinno być dość łatwe, ale zamiana gałęzi w wierszu polecenia może być nieco inna.
Najpierw skonfiguruj projekt w Visual Studio Code:
Zauważ tutaj, że otwieram również zintegrowany terminal, naciskając skrót CMD + P (jestem na macOS, więc twój skrót może być inny). Następnie wpisuję polecenie, aby sprawdzić gałąź deweloperską.
Gdy to zrobisz, twoje lokalne repozytorium powinno przełączyć się na gałąź deweloperską. Możesz potwierdzić, że jest to gałąź, nad którą pracujesz, wpisując:
$ git branchA następnie przejrzyj zawartość terminala. Ściśle mówiąc, należy podkreślić rozwój .
W tym momencie wprowadzimy do projektu kilka nowych plików. Na końcu tego samouczka możesz utworzyć ściąganie, aby uzyskać wszystko, co zamierzam tutaj udokumentować. Ale ponieważ cel tego, co robimy, jest dwojaki, ważne jest, aby upewnić się, że robimy to we właściwej kolejności, ponieważ pierwszym krokiem jest coś, czego używam w każdym projekcie dla WordPressa w tym momencie.
Więc z tym powiedziawszy, spójrzmy.
Kompozytor i jakość kodu
Pierwszą rzeczą, którą lubię robić, jest stworzenie szeregu narzędzi, które wymuszają jakość kodu. Osiąga się to dzięki różnym pakietom Composer. Obejmują one:
- GrumPHP. Narzędzie jakości kodu PHP. Nie lekceważ jasności i stopnia, w jakim to repozytorium jest pełne informacji. Jeśli kiedykolwiek utkniesz z którymkolwiek z innych wymienionych tutaj narzędzi, najpierw przejrzyj dokumentację w tym repozytorium.
- Narzędzie do naprawy PHP CS. Narzędzie do automatycznego rozwiązywania problemów ze standardami kodowania PHP.
- PHP Parallel Lint. To narzędzie sprawdza składnię plików PHP szybciej niż sprawdzanie szeregowe z bardziej wyszukanym wyjściem.
- PHPMD. To narzędzie pobiera daną bazę kodu źródłowego PHP i szuka kilku potencjalnych problemów w tym źródle
- Parser PHP. Parser jest przydatny do analizy statycznej, manipulacji kodem i w zasadzie każdej innej aplikacji zajmującej się kodem programowo.
- Pełnomocnik. Ta biblioteka ma na celu dostarczenie abstrakcji do generowania różnego rodzaju klas proxy.
Chcę być wolny od dwóch rzeczy:
- Powyższe narzędzia to absolutne minimum, którego używam, i prawdopodobnie zobaczysz, że używam dodatkowych narzędzi w przyszłości,
- powyższe narzędzia pomogą wymusić reguły jakości kodu przed umieszczeniem kodu w repozytorium. Ma uzupełniać konfigurację w twoim IDE.
Aby skonfigurować i uruchomić te narzędzia w ramach projektu, musimy utworzyć plik composer.json, który wygląda tak :
{
"name": "wordpress-widget-boilerplate/wordpress-widget-boilerplate",
"description": "An organized, maintainable boilerplate for building widgets using WordPress best practices.",
"type": "wordpress-plugin",
"license": "GPL-3.0-or-later",
"homepage": "https://github.com/tommcfarlin/WordPress-Widget-Boilerplate",
"authors": [
{
"name": "Tom McFarlin",
"email": "tom@pressware.co",
"homepage": "https://pressware.co"
}
],
"support": {
"issues": "https://github.com/tommcfarlin/WordPress-Widget-Boilerplate/issues"
},
"config": {
"preferred-install": "dist",
"platform": {
"php": "7.1"
}
},
"repositories": [
{
"type": "composer",
"url": "https://wpackagist.org"
}
],
"require": {
"php": "7.1",
"composer/installers": "^1.4"
},
"require-dev": {
"friendsofphp/php-cs-fixer": "^2.13.1",
"jakub-onderka/php-parallel-lint": "^1.0.0",
"phpmd/phpmd": "^v2.6.0",
"nikic/php-parser": "^4.0",
"ocramius/proxy-manager": "^2.0.0",
"phpro/grumphp": "^0.13.1"
},
"scripts": {
"test": [
"./vendor/bin/grumphp run"
]
},
"minimum-stability": "stable"
}Pamiętaj, możesz to zrobić ręcznie na końcu tego postu. Jeśli jednak chcesz kontynuować, możesz to zrobić ręcznie. Nigdy nie chciałbym cię do tego zniechęcać.
Po utworzeniu pliku composer.json upewnij się, że uruchamiasz następujące polecenie z terminala:
$ composer installTo może zająć troche czasu; jednak po zakończeniu powinieneś otrzymać następujący komunikat:
Uważaj! GrumPHP sniffuje twoje commity!
Aby przetestować go na sucho, wpisz w terminalu następujące polecenie:
$ vendor/bin/grumphp runW zależności od tego, jak pracujesz z projektem, możesz zobaczyć dane wyjściowe, które wyglądają mniej więcej tak:
Ale jest jeszcze więcej pracy. Mianowicie musimy:
- zaktualizuj nasz plik .gitignore ,
- wprowadzić konfigurację dla GrumPHP
- wprowadzić konfigurację dla PHPMD,
- wprowadzić konfigurację dla PHPCS,
- ostatecznie zrestrukturyzuj strukturę katalogów schematu.
Wszystko, aż do ostatniego kroku, zamierzamy zrobić w tym poście.
Aktualizacja pliku ignorowania
Po pierwsze, nie chcemy zatwierdzać katalogu dostawcy ani pliku blokady kompozytora. Mogą być generowane za każdym razem, gdy użytkownik pobiera katalog. Mogą łatwo stracić synchronizację i dodać ogromny rozmiar do katalogu projektu.
W tym celu twój plik gitignore powinien wyglądać tak :
*.DS_Store
*.log
wp-config.php
wp-content/advanced-cache.php
wp-content/backup-db/
wp-content/backups/
wp-content/blogs.dir/
wp-content/cache/
wp-content/upgrade/
wp-content/uploads/
wp-content/mu-plugins/
wp-content/wp-cache-config.php
wp-content/plugins/hello.php
/.htaccess
/license.txt
/readme.html
/sitemap.xml
/sitemap.xml.gz
vendor/
composer.lockTo mówi wtyczce, aby ignorowała wszystko oprócz tego, co znajduje się w katalogu głównym wtyczek (i niektórych katalogów, które utworzymy) wraz z kilkoma podstawowymi plikami, do których przywykliśmy w instalacjach WordPress.
Niektóre z tego, co widzisz, takie jak wp-config.php lub wp-content/backups, których nigdy nie zobaczysz w kontekście wtyczki, ale są to standardowe dyrektywy ignorujące WordPressa, które lubię mieć pod ręką.
Zauważysz, że dodałem również plik blokady dostawcy i kompozytora na dole pliku.
Skonfiguruj GrumPHP
GrumPHP może wiele zdziałać, a jeśli spędziłeś czas na przeglądaniu repozytorium przed przeczytaniem tak daleko, prawdopodobnie wiesz o tym; jednak zamierzam zachować jak najszczuplejszą, aby zawierała instrukcje, których potrzebuje do używanych przez nas narzędzi, i nic więcej.
parameters:
git_dir: .git
bin_dir: vendor/bin
process_timeout: 120
tasks:
securitychecker:
composer:
jsonlint:
xmllint:
yamllint:
phplint:
exclude:
- vendor/
phpcs:
metadata:
priority: 200
phpcsfixer2:
allow_risky: true
config: '.php_cs.dist'
metadata:
priority: 300
phpparser:
visitors:
forbidden_function_calls:
blacklist:
- "exit"
- "var_dump"
phpversion:
project: '7.1'
phpmd:
exclude: ['vendor']
ruleset: ['phpmd.xml']Krótko mówiąc, oznacza to przeprowadzenie różnych kontroli pod kątem:
- bezpieczeństwo,
- kompozytor,
- JSON,
- XML,
- Jaml,
- PHP,
- PHPCS,
- Parser PHP,
- PHPMD,
- i więcej.
Gdy skończymy konfigurować wszystko inne, na pewno pokażę Ci, jak to wszystko do siebie pasuje. Ale najpierw zakończmy konfigurację pozostałych naszych narzędzi.
PHPCS
Wykorzystuje to dwa oddzielne pliki – plik dist i plik XML – z których każdy służy innym, choć bardzo pomocnym celom.
Pierwszy plik, php_cs.dist, który zobaczysz w repozytorium pod koniec tego postu, zawiera nagłówek, który jest stosowany do wszystkich plików PHP w naszym projekcie. Wymusza również kilka innych reguł, które poprawiają jakość kodu.
Reguły nie wymagają wyjaśnień, a ich egzekwowanie można sprawdzić, przeglądając każdą ze zdefiniowanych reguł .
<?php
$header = <<<'EOF'
This file is part of the WordPress Widget Boilerplate
(c) Tom McFarlin <tom@tommcfarlin.com>
This source file is subject to the GPL license that is bundled
with this source code in the file LICENSE.
EOF;
return PhpCsFixerConfig::create()
->setRiskyAllowed(true)
->setRules([
'@PHP56Migration' => true,
'@Symfony' => true,
'@Symfony:risky' => true,
'align_multiline_comment' => true,
'array_syntax' => ['syntax' => 'short'],
'blank_line_before_statement' => true,
'combine_consecutive_issets' => true,
'combine_consecutive_unsets' => true,
// one should use PHPUnit methods to set up expected exception instead of annotations
'general_phpdoc_annotation_remove' => ['annotations' => ['expectedException', 'expectedExceptionMessage', 'expectedExceptionMessageRegExp']],
'header_comment' => ['header' => $header],
'heredoc_to_nowdoc' => true,
'list_syntax' => ['syntax' => 'long'],
'method_argument_space' => ['ensure_fully_multiline' => true],
'method_chaining_indentation' => false,
'no_extra_consecutive_blank_lines' => ['tokens' => ['break', 'continue', 'extra', 'return', 'throw', 'use', 'parenthesis_brace_block', 'square_brace_block', 'curly_brace_block']],
'no_null_property_initialization' => true,
'no_short_echo_tag' => true,
'no_unneeded_curly_braces' => true,
'no_unneeded_final_method' => true,
'no_unreachable_default_argument_value' => true,
'no_useless_else' => true,
'no_useless_return' => true,
'ordered_class_elements' => true,
'ordered_imports' => true,
'php_unit_construct' => true,
'php_unit_test_class_requires_covers' => true,
'php_unit_dedicate_assert' => true,
'phpdoc_add_missing_param_annotation' => true,
'phpdoc_order' => true,
'phpdoc_types_order' => ['null_adjustment' => 'always_last'],
'semicolon_after_instruction' => true,
'single_line_comment_style' => true,
'visibility_required' => ['const', 'property', 'method'],
'yoda_style' => true,
])
->setFinder(
PhpCsFixerFinder::create()
->exclude(__DIR__. '/vendor/*')
->in([
__DIR__. '/src'
])) ;Następnie będziesz chciał również utworzyć plik XML, aby uzupełnić powyższy plik. Zauważysz, że w dostarczonym przeze mnie pliku, tego właśnie używam w mojej pracy w Pressware. Ponadto potwierdza również katalog testów .
W tym momencie nie mamy napisanych żadnych testów jednostkowych, ale jeśli zdecydujesz się wprowadzić je do swojego widżetu, będzie on gotowy do ich poprawnej obsługi.
<?xml version="1.0"?>
<ruleset name="Pressware">
<description>Pressware, LLC Coding Standards</description>
<!-- Scan all files in directory -->
<file>./src</file>
<file>./tests</file>
<exclude-pattern>./tests/phpunit/*</exclude-pattern>
<!-- Scan only PHP files -->
<arg name="extensions" value="php"></arg>
<!-- Show colors in console -->
<arg value="-colors"></arg>
<!-- Show sniff codes in all reports -->
<arg value="ns"></arg>
<!-- Use PSR-2 as a base -->
<rule ref="PSR2"></rule>
<rule ref="Generic.Arrays.DisallowLongArraySyntax.Found" ></rule>
<!-- Force 2 spaces indentation -->
<rule ref="Generic.WhiteSpace.ScopeIndent">
<properties>
<property name="indent" value="4"></property>
<property name="tabIndent" value="false"></property>
</properties>
</rule>
</ruleset>Jest tylko mały zestaw konfiguracji, który określam tutaj, ale uważam, że jest on jak dotąd więcej niż wystarczający dla moich potrzeb. Gdy odkryję więcej lub zdecyduję się użyć więcej, z pewnością zaktualizuję zawartość w przyszłych postach.
Skonfiguruj PHPMD
I na koniec musimy skonfigurować PHP Mess Detector (lub PHPMD). Na szczęście używa to pliku XML, który będzie używał zestawów reguł zdefiniowanych w pakiecie zainstalowanym przez Composer. Wszystko, co musimy zrobić, to odwołać się do reguły w pliku konfiguracyjnym.
Po drugie, zapewnimy również małe wykluczenie dla nazwy ShortVariable, jak widać w następującym skrócie :
<?xml version="1.0" encoding="UTF-8" ?>
<ruleset
name="VersionEyeModule rules"
xmlns="http://pmd.sf.net/ruleset/1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://pmd.sf.net/ruleset/1.0.0 http://pmd.sf.net/ruleset_xml_schema.xsd"
xsi:noNamespaceSchemaLocation="http://pmd.sf.net/ruleset_xml_schema.xsd"
>
<rule ref="rulesets/cleancode.xml" ></rule>
<rule ref="rulesets/codesize.xml" ></rule>
<rule ref="rulesets/controversial.xml" ></rule>
<rule ref="rulesets/design.xml" ></rule>
<rule ref="rulesets/unusedcode.xml" ></rule>
<rule ref="rulesets/naming.xml">
<exclude name="ShortVariable"></exclude>
</rule>
<rule ref="rulesets/naming.xml/ShortVariable"
since="0.2"
message="Avoid variables with short names like {0}. Configured minimum length is {1}."
class="PHPMDRuleNamingShortVariable"
externalInfoUrl="http://phpmd.org/rules/naming.html#shortvariable">
<priority>3</priority>
<properties>
<property name="minimum" description="Minimum length for a variable, property or parameter name" value="3"></property>
<property name="exceptions" value="id,q,w,i,j,v,e,f,fp" ></property>
</properties>
</rule>
</ruleset>A kiedy wszystko to będzie gotowe, powinniśmy być w stanie ponownie uruchomić GrumPHP z wiersza poleceń i uzyskać nieco inny zestaw wyników.
Ponownie uruchamiam GrumPHP
Wprowadź w terminalu:
$ vendor/bin/grumphp runPowinieneś zobaczyć coś takiego:
Inne wyniki niż za pierwszym razem, co? Dzieje się tak, ponieważ naruszamy niektóre zasady i standardy, które są nowoczesną częścią PHP i programowania obiektowego.
I to właśnie zamierzamy posprzątać w następnym poście.
Nadchodzi
Skąd więc bierze się obiektowo zorientowana natura tego? Do tego momentu mówiliśmy o wykorzystaniu API Widgets jako modelu obiektowego do pisania kodu obiektowego w WordPressie.
Niektóre z tego, co do tej pory zrobiliśmy, były właśnie tym (omawiając jego zasady, widząc, jak jest rozplanowany i nie tylko).
Ale jak wspomniałem na początku tego postu, najpierw stworzenie narzędzi jakości kodu zapewnia nam podstawę, której możemy użyć, gdy dokonamy refaktoryzacji boilerplate’u (co oczywiście musimy zrobić, biorąc pod uwagę ilość czerwieni pokazaną przez GrumPHP).
I od tego zaczniemy w kolejnym poście z tej serii.