Difference between revisions of "Deploying an Update Server/pl"

Revision as of 13:28, 4 April 2021

Wprowadzenie

Ten samouczek ma na celu nauczenie programistów, jak utworzyć serwer aktualizacji do integracji z systemem aktualizacji wprowadzonym w Joomla!. Dodając listę serwerów aktualizacji do manifestu rozszerzenia, programiści umożliwiają użytkownikom aktualizowanie rozszerzeń za pośrednictwem Menadżera Aktualizacji Rozszerzeń (zobacz ekran pomocy Joomla 3.x).

Definiowanie serwera aktualizacji

Aby móc korzystać z tej funkcji, serwer aktualizacji musi być zdefiniowany w manifeście rozszerzenia. Ta definicja może być używana we wszystkich rozszerzeniach Joomla! 2.5 oraz nowszych kompatybilnych, ale nie jest dostępna dla szablonów. Możesz użyć dwóch opcji dla swojego typu serwera: kolekcji lub rozszerzenia. Zostaną one wkrótce szczegółowo objaśnione.Ten kod powinien być dodany do pliku manifestu rozszerzenia, wewnątrz głównego elementu rozszerzenia. Serwer aktualizacji jest zdefiniowany w następujący sposób dla każdego typu:

 <extension>
 <...>
 <updateservers>
    <server type="collection">https://example.com/list.xml</server>
    <server type="extension" priority="2" name="My Extension's Updates">http://example.com/extension.xml</server>
 </updateservers>
 </extension>

W tagu <updateservers> można zdefiniować wiele serwerów. Jeśli masz więcej niż jeden serwer aktualizacji, możesz ustawić inny priorytet dla każdego znich. W ten sposób możesz kontrolować kolejność, w jakiej sprawdzane są serwery aktualizacji.

Typy serwerów

Kolekcja

Typ serwera "kolekcja" umożliwia programistom definiowanie manifestu rozszerzenia w celu pobierania aktualizacji z kolekcji. Ten typ serwera może być używany, jeśli deweloper chce zdefiniować wszystkie aktualizacje swojego rozszerzenia w jednym pliku (niezalecane) lub jeśli jego rozszerzenie ma wiele rozszerzeń podrzędnych, które nie są dystrybuowane lub aktualizowane w tym samym czasie (takie jak typ rozszerzenia pakietu). Poniższy przykład to definicja „kolekcji” używana przez aktualizator podczas przetwarzania aktualizacji podstawowych Joomla!:

 <extensionset name="Joomla Core" description="Joomla! Core">
    <extension name="Joomla" element="joomla" type="file" version="1.7.0" detailsurl="https://update.joomla.org/core/extension.xml"/>
 </extensionset>

Wszystkie definicje muszą być zdefiniowane pomiędzy tagami <extensionset> w manifeście kolekcji. Tag <extensionset> posiada dwa opcjonalne parametry: nazwę i opis. Dla każdego rozszerzenia, do którego odwołuje się ta kolekcja, wymagany jest oddzielny tag <extension>. Tag <extension> ma następujące parametry, z których wszystkie są wymagane do prawidłowego przetwarzania aktualizacji:

• name – nazwa rozszerzenia
• element – nieprzetłumaczona nazwa rozszerzenia, np. mod_custom
• type – typ rozszerzenia (komponent, moduł, plugin, itp.)
• version – najnowsza wersja rozszerzenia
• detailsurl – adres URL pliku XML, który zawiera indywidualne definicje aktualizacji dla tego rozszerzenia.

Rozszerzenie

Typ serwera "extension" pozwala deweloperom na zdefiniowanie manifestu rozszerzenia w celu pobierania aktualizacji z manifestu pojedynczego rozszerzenia. Wszystkie manifesty kolekcji ostatecznie wskazują na ten plik XML. Wszystkie aktualizacje w tym pliku muszą być zdefiniowane po tagu <updates> na początku pliku. Poniższy przykład to definicja aktualizacji dla Joomla! w wersji 3.9.6:

<updates>
	<update>
		<name>Joomla! 3.9</name>
		<description>Joomla! 3.9 CMS</description>
		<element>joomla</element>
		<type>file</type>
		<version>3.9.6</version>
		<infourl title="Joomla!">https://www.joomla.org/announcements/release-news/5765-joomla-3-9-6-release.html</infourl>
		<downloads>
			<downloadurl type="full" format="zip">https://downloads.joomla.org/cms/joomla3/3-9-6/Joomla_3.9.6-Stable-Update_Package.zip</downloadurl>
			<downloadsource type="full" format="zip">https://github.com/joomla/joomla-cms/releases/download/3.9.6/Joomla_3.9.6-Stable-Update_Package.zip</downloadsource>
			<downloadsource type="full" format="zip">https://update.joomla.org/releases/3.9.6/Joomla_3.9.6-Stable-Update_Package.zip</downloadsource>
		</downloads>
		<tags>
			<tag>stable</tag>
		</tags>
		<sha256>05157273aadd3045564ee44373ea3643b437fa5321d17993a3119b38b04578e2</sha256>
		<sha384>ebd9b0666fbe84e20a420a4bcd6c10d306fc4dee4edbbe8e2133c85f0fb84e59be5a50aa97cb38c068b77f77f6bbc091</sha384>
		<sha512>a4c47644ceeaeec28944e0c74160203cf12037e0ea1439022e95055dfb6716de172667ce6d9164f12bb519d9cfcf1fdc728abea00f853b41debc7d2740f2b711</sha512>
		<maintainer>Joomla! Production Department</maintainer>
		<maintainerurl>https://www.joomla.org</maintainerurl>
		<section>STS</section>
		<targetplatform name="joomla" version="3.[789]" />
		<php_minimum>5.3.10</php_minimum>
</update>
</updates>

W poniższej sekcji opisano elementy pojedynczego elementu aktualizacji.

• name – nazwa rozszerzenia, ta nazwa będzie wyświetlana w kolumnie Nazwa w widoku Menedżera Aktualizacji Rozszerzeń (wymagane)
• description – krótki opis rozszerzenia (opcjonalnie) - jeśli zdecydujesz się na użycie <![CDATA[]]>, podwójne cudzysłowy złamią formatowanie HTML. Używaj pojedynczych cudzysłowów w swoich encjach HTML.
• element – zainstalowana nazwa rozszerzenia (wymagana). W przypadku wtyczek, musi to być taka sama wartość jak wartość atrybutu pluginu dla głównego pliku w manifeście wtyczki. Dla <filename plugin = "pluginname">pluginname.php</filename> wartością elementu powinna być nazwa wtyczki.
• type – typ rozszerzenia (komponent, moduł, plugin, itp.) (wymagane)
• folder – specyficzny dla wtyczek, ten tag opisuje typ aktualizowanej wtyczki (zawartość, system itp.) (wymagany w przypadku wtyczek)
• client – wymagane dla modułów i szablonów od 3.2.0. - identyfikator klienta rozszerzenia, który można znaleźć, zaglądając do tabeli #_extensions. Użyj 0 dla „strony” i 1 dla „administratora”. Ostrzeżenie! Wtyczki i moduły witryny są automatycznie instalowane z klientem 0 (strona), ale będziesz musiał określić klienta w aktualizacji lub domyślnie będzie to 1 (administrator), znaleziona aktualizacja nie zostanie wyświetlona, ponieważ nie będzie pasować do żadnego rozszerzenia.
  • Warning: nazwa tagu <client> dla Joomla! 2.5 to <client_id> dla 1.6 i 1.7. Jeśli używasz <client_id> (zamiast <client>) w witrynie 2.5, zostanie on zignorowany.
• version – wersja wydania (wymagana)
• infourl – adres URL wskazujący użytkownikom informacje o aktualizacji (opcjonalnie) (w CMS 2.5, jeśli jest ustawiony, ten adres URL będzie wyświetlany w widoku aktualizacji)
• downloads – sekcja zawierająca listę wszystkich lokalizacji pobierania
  • downloadurl – adres URL, z którego należy pobrać rozszerzenie; tag <downloadurl> ma dwa wymagane parametry:
    • type – typ pakietu (full lub upgrade)
    • format – format paczki (zip, tar itp.)
  • downloadsource – opcjonalny. Od Joomla 3.8.3. alternatywny adres URL do pobrania rozszerzenia w przypadku niepowodzenia połączenia z <downloadurl>. Dozwolonych jest wiele tagów <downloadsource>. Tag <downloadsource> ma dwa wymagane parametry:
    • type – typ pakietu (pełny lub uaktualnienie)
    • format – format paczki (zip, tar itp.)
  • NB – nie może być nowej linii przed ani po adresie URL; wszystko musi znajdować się w jednej linii, w przeciwnym razie pojawi się błąd podczas łączenia się z serwerem: źle sformułowany po uruchomieniu aktualizacji
• tags – lista tagów związanych z wersją. Joomla! 3.4 i późniejsze używają tego do określenia poziomu stabilności aktualizacji. Prawidłowe tagi to:
  • dev: wersje rozwojowe, bardzo niestabilne i pre-alpha (np. nocne kompilacje)
  • alpha: oprogramowanie o jakości alfa (niezaimplementowane funkcje, błędy krytyczne)
  • beta: oprogramowanie o jakości beta (wszystkie funkcje zaimplementowane, możliwe błędy krytyczne, niemal pewne drobne błędy)
  • rc: wydanie oprogramowania wysokiej jakości, wydanie kandydujące (brak błędów krytycznych, drobne błędy mogą nadal być obecne)
  • stable: wersja nadająca się do użytkowania zgodnie z założeniami autorów, wszystkie inne znaczniki są obecnie ignorowane. Jeśli podasz więcej niż jeden tag zawierający jedno z wyżej wymienionych słów kluczowych, tylko OSTATNI tag będzie brany pod uwagę. Jeśli nie podasz żadnych znaczników, Joomla! założy, że jest to wersja stabilna..
• maintainer – nazwa opiekuna rozszerzenia (podobnie jak w tagu <author> w manifeście) (opcjonalnie)
• maintainerurl – witryna opiekuna rozszerzenia (podobna do tagu <authorUrl> w manifeście) (opcjonalnie)
• section – opcjonalne (nieznane zastosowanie)
• targetplatform – tag definiujący wymagania platformy (od jest również używany do wykrywania zgodności rozszerzeń dla komponentu aktualizacji Joomla ) wymaga następujących elementówː
  • name – nazwa zależności platformy; na dzień dzisiejszy powinna to być TYLKO "joomla"
  • version – wersja Joomla!, którą obsługuje rozszerzenie
  • min_dev_level oraz max_dev_level – atrybuty te zostały dodane w wersji 3.0.1, aby umożliwić wybór platformy docelowej na podstawie poziomu deweloperskiego ("z" w x.y.z). Są opcjonalne. Możesz określić jedną lub obie. W przypadku pominięcia dopasowywane są wszystkie poziomy deweloperskie. Na przykład następujący kod odpowiada wersjom 4.0.0 i 4.0.1. <targetplatform name="joomla" version="4.0" min_dev_level="0" max_dev_level="1"/>
    • Note: If your extension is Joomla! 2.5 and/or 3.1 compatible, you will be required to have separate <update> definitions for each version due to the manner in which the updater checks the version if you specify a number. However to show your extension on all Joomla versions that support automatic updates (and thus mark as compatible with all future unreleased versions of Joomla in Joomla Update) add <targetplatform name="joomla" version=".*"/>. If you want your extension to show on all versions then rather than specifying a version in the version tag add in <targetplatform name="joomla" version="3.[012345]"/>. This will show the update to all 3.x versions from version 3.0 to 3.5. If you want to include version 3.10 you can use an | like this: <targetplatform name="joomla" version="3.[012345]|10"/>. If you want to show the updates for all 3.8.x versions and all 3.10.x versions you can use <targetplatform name="joomla" version="3.(8|10)"/>
• php_minimum – Beginning with 3.2.2, a minimum supported PHP version can be supplied in the update stream. If the server does not meet the minimum, a message is displayed to the user advising that an update is available but cannot be installed due to unsupported requirements.
• supported_databases – Beginning with 3.7, a minimum supported databases + version check can be supplied in the update stream. When the server does not meet the minimum, a message is displayed to the user advising that an update is available but cannot be installed due to unsupported requirements. Note: As of 3.9.12 there is also a special case for mariadb so you can set a specific minimum version for that too now.
  • An example could look like this: <supported_databases mysql="5.5.3" mariadb="10.1" postgresql="9.2" mssql="10.50.1600.1" />
• sha256, sha384, sha512 – Optional. Since Joomla 3.9.0 you can add file checksums in these hash formats. Be aware that in Joomla 3 only a notice is shown on updates if a checksum is not correct. That's all. The update doesn't stop then. In Joomla 4 updates and installations will stop if a provided checksum doesn't match.

A separate <update> definition will be required for each version of your extension you release.

The values of element, type, client_id and folder should match those in the table #_extensions.

Important for plugins: Plugins have to include <folder> and <client> elements to work properly

Troubleshooting

• SQL update script is not executed during update.

If the SQL update script (for example, in the folder sql/updates/mysql) does not get executed during the update process, it could be because there is no version number in the #_schemas table for this extension prior to the update. This value is determined by the last script name in the SQL updates folder. If this value is blank, no SQL scripts will be executed during that update cycle. To make sure this value is set correctly, make sure you have a SQL script in this folder with its name as the version number (for example, 1.2.3.sql if the version is 1.2.3). The file can be empty or just have a SQL comment line. This should be done in the old version — the one before the update. Alternatively, you can add this value to the #_schemas using a SQL query.

Supporting Tools