Joomla! Documentation™

Joomla! 

3.x

Joomla! 

2.5

Versie opmerking

Deze handleiding is opgesplitst in twee losse delen:

• Invoegen, bijwerken en verwijderen van gegevens in de database.
• Selecteren van gegevens uit één of meer tabellen en het ophalen op diverse verschillende formaten.

Deze sectie van de documentatie kijkt naar het invoegen, bijwerken en verwijderen van gegevens uit een databasetabel. Klik, om het andere deel te zien hier

Inleiding

Joomla biedt een geavanceerde database abstractie laag om het gebruik door externe ontwikkelaars te vereenvoudigen. Nieuwe versies van de Joomla Platform API bieden extra functionaliteit welke de database laag verder uitbreidt en bevat functies zoals koppelingen naar een groot aantal database servers en de query-koppeling om de leesbaarheid te vergroten van verbindingscode an het vereenvoudigen van het coderen van SQL.

Joomla kan verschillende soorten SQL database systemen gebruiken en draaien op diverse omgevingen met verschillende tabel-voorvoegsels. Naast deze functies maakt de class automatisch de database verbinding aan. Naast het instantiëren van het object heeft u slechts twee regels code nodig om het resultaat uit de database te krijgen in een verscheidenheid aan formaten. Het gebruik van de Joomla database laag garandeert een maximum aan compatibiliteit en flexibiliteit voor uw extensie.

De query

Joomla's database query's is veranderd sinds het nieuwe Joomla Framework werd geïntroduceerd. "query-chaining" is nu de aanbevolen methode om database query's op te bouwen (hoewel string query's nog ondersteund worden).

Query chaining verwijst naar de methode van koppelen van een aantal methodes, de één na de ander waarbij ieder methode een object terug geeft die de volgende methode kan ondersteunen, waardoor de leesbaarheid verbeterd wordt en de code vereenvoudigd.

Om een nieuwe instantie van de JDatabaseQuery class te verkrijgen gebruiken we de JDatabaseDriver getQuery methode:

$db = JFactory::getDbo();

$query = $db->getQuery(true);

De JDatabaseDriver::getQuery heeft een optioneel argument, $new, welk 'true' of 'false' kan zijn (de standaard is 'false').

Om onze data source te bevragen kunnen we een aantal JDatabaseQuery methodes aanroepen; deze methodes kapselen de gegevens source's query-taal (in de meeste gevallen SQL) in, verbergen query-specifieke syntaxis voor de ontwikkelaar en verhogen de overdraagbaarheid van de broncode van de ontwikkelaar.

Enkele van de meest gebruikte methodes omvatten; select, from, join, where en order. Er zijn ook methodes zoals insert, update en delete voor het wijzigen van de gegevensopslag. Door het koppelen van deze en andere methode aanroepen, kunt u bijna iedere query maken ten opzichte van uw database zonder afbreuk te doen aan de overdraagbaarheid van uw code.

Het invoegen van een record

SQL gebruiken

De JDatabaseQuery class biedt een aantal methodes voor het bouwen van insert query's, waarvan de meest gebruikte zijn

// Get a db connection.
$db = JFactory::getDbo();

// Create a new query object.
$query = $db->getQuery(true);

// Insert columns.
$columns = array('user_id', 'profile_key', 'profile_value', 'ordering');

// Insert values.
$values = array(1001, $db->quote('custom.message'), $db->quote('Inserting a record using insert()'), 1);

// Prepare the insert query.
$query
    ->insert($db->quoteName('#__user_profiles'))
    ->columns($db->quoteName($columns))
    ->values(implode(',', $values));

// Set the query using our newly populated query object and execute it.
$db->setQuery($query);
$db->execute();

(Here the quoteName() function adds appropriate quotes around the table and column names to avoid conflicts with any database reserved word, now or in the future.) To get the ID of the row that you just inserted, you can use the 'insertid' method, for example.

// Get the row that was just inserted
$new_row_id = $db->insertid();

How to store empty value as NULL

If your default value of a column is NULL, you should not add that column name in the array. Let the database system store NULL as the default value. If the default value of a column is not NULL and it is allowed to store NULL values, you should specify that in the code. See how to do it in the following example.

// Get a db connection.
$db = JFactory::getDbo();

// Create a new query object.
$query = $db->getQuery(true);

/** First Case [NULL as default value] **/
// The column 'profile_value' has NULL as default value. So, we will not add it to the array. The database engine will store NULL as value for column 'profile_value'.
// $columns = array('user_id', 'profile_key', 'profile_value', 'ordering');
$columns = array('user_id', 'profile_key', 'ordering');

// Insert values.
$values = array(1001, $db->quote('custom.message'), 1);

/** Second Case [string as default value and you can also store NULL value] **/
// The column 'profile_value' has empty string '' as default value but we can also store NULL value. So, we have to add the column name and NULL value to $columns and $values.
$columns = array('user_id', 'profile_key', 'profile_value', 'ordering');

// Insert values.
$values = array(1001, $db->quote('custom.message'), $db->quote('NULL'), 1);

Een object gebruiken

De JDatabaseDriver class biedt ook een makkelijke methode voor het opslaan van een object direct in de database zodat we een record aan een tabel kunnen toevoegen zonder een regel SQL te schrijven.

// Create and populate an object.
$profile = new stdClass();
$profile->user_id = 1001;
$profile->profile_key='custom.message';
$profile->profile_value='Inserting a record using insertObject()';
$profile->ordering=1;

// Insert the object into the user profile table.
$result = JFactory::getDbo()->insertObject('#__user_profiles', $profile);

Merk op dat we de tabelnaam geen quotes hoeven te geven ; de insertObject methode doet dit voor ons.

De insertObject methode rapporteert een fout als er een probleem is bij het invoegen van het record in de database tabel.

Als u een unieke primaire sleutelwaarde opgeeft (zoals in het bovenstaande voorbeeld), wordt het ten zeerste aanbevolen dat u in de tabel die kolomwaarde selecteert voordat u probeert in te voegen.

Als u eenvoudigweg de volgende rij in uw tabel invoegt (dat wil zeggen dat de database een primaire sleutelwaarde genereert), kunt u de kolomnaam van de primaire sleutel opgeven als de derde parameter van de methode insertObject () en de methode zal het object bijwerken met de nieuw gegenereerde primaire sleutelwaarde.

Bijvoorbeeld, gegeven het volgende statement:

$result = $dbconnect->insertObject('#__my_table', $object, 'primary_key');

na uitvoering wordt $ object-> primary_key bijgewerkt met de primaire sleutelwaarde van de nieuw ingevoegde rij.

HINT: Stel $object->primary_key in op null of 0 (zero) voor invoegen.

How to store empty value as NULL when insert an object

If your default value of a column is NULL, you should not add that column name to the object. Let the database system store NULL as the default value. If the default value of a column is not NULL and it is allowed to store NULL values, you should specify that in the code. See how to do it in the following example.

// Create and populate an object.
$profile = new stdClass();
$profile->user_id = 1001;
$profile->profile_key='custom.message';
$profile->ordering=1;

/** First Case [NULL as default value] **/
// The column 'profile_value' has NULL as default value. So, we will not add it to the object. The database engine will store NULL as value for column 'profile_value'.
// $profile->profile_value='Inserting a record using insertObject()';

/** Second Case [string as default value and you can also store NULL value] **/
// The column 'profile_value' has empty string '' as default value but we can also store NULL value. So, we have to add the column name and NULL value as its value.
$profile->profile_value = $db->quote('NULL');

// Insert the object into the user profile table.
$result = JFactory::getDbo()->insertObject('#__user_profiles', $profile);

Een record bijwerken

SQL gebruiken

De JDatabaseQuery class biedt ook methodes voor het bouwen van update query's, in het bijzonder update en set. We hergebruiken ook een andere methode die we gebruikten bij het aken van select statements, de where methode.

$db = JFactory::getDbo();

$query = $db->getQuery(true);

// Fields to update.
$fields = array(
    $db->quoteName('profile_value') . ' = ' . $db->quote('Updating custom message for user 1001.'),
    $db->quoteName('ordering') . ' = 2',

    // If you would like to store NULL value, you should specify that.
    $db->quoteName('avatar') . ' = NULL',
);

// Conditions for which records should be updated.
$conditions = array(
    $db->quoteName('user_id') . ' = 42', 
    $db->quoteName('profile_key') . ' = ' . $db->quote('custom.message')
);

$query->update($db->quoteName('#__user_profiles'))->set($fields)->where($conditions);

$db->setQuery($query);

$result = $db->execute();

Een object gebruiken

Zoals insertObject, biedt de JDatabaseDriver class een makkelijke methode voor het updaten van een object.

Hieronder zullen we onze custom tabel updaten met nieuwe waarden via een bestaand primaire-sleutel ID:

$updateNulls = true;

// Create an object for the record we are going to update.
$object = new stdClass();

// Must be a valid primary key value.
$object->id = 1;
$object->title = 'My Custom Record';
$object->description = 'A custom record being updated in the database.';

// If you would like to store NULL value, you should specify that.
$object->short_description = null;

// Update their details in the users table using id as the primary key.
// You should provide forth parameter with value TRUE, if you would like to store the NULL values.
$result = JFactory::getDbo()->updateObject('#__custom_table', $object, 'id', $updateNulls);

Net als insertObject, zorgt updateObject voor de quotes rond de tabelnamen voor ons.

De updateObject methode geeft een fout als er een probleem bij het updaten van een record in de database-tabel is.

We moeten ervoor zorgen dat het record al bestaat alvorens te proberen het bij te werken, zodat we een soort record controle moeten toevoegen voor het uitvoeren van de updateObject methode.

Een record verwijderen

Tenslotte is er ook een delete methode om records uit de database te verwijderen.

$db = JFactory::getDbo();

$query = $db->getQuery(true);

// delete all custom keys for user 1001.
$conditions = array(
    $db->quoteName('user_id') . ' = 1001', 
    $db->quoteName('profile_key') . ' = ' . $db->quote('custom.%')
);

$query->delete($db->quoteName('#__user_profiles'));
$query->where($conditions);

$db->setQuery($query);

$result = $db->execute();

Sample Module Code

Below is the code for a simple Joomla module which you can install and run to demonstrate use of the JDatabase functionality for updating records in the database, and which you can adapt to experiment with some of the concepts described above. If you are unsure about development and installing a Joomla module then following the tutorial at Creating a simple module will help. Important note: In any Joomla extensions which you develop that you should avoid accessing the core Joomla tables directly like this and should instead use the Joomla APIs if at all possible, because the database structures may change without warning. In a folder mod_db_update create the following 2 files:

mod_db_update.xml

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="3.1" client="site" method="upgrade">
    <name>Database update demo</name>
    <version>1.0.1</version>
    <description>Code demonstrating use of Joomla Database class to perform SQL UPDATE statements</description>
    <files>
        <filename module="mod_db_update">mod_db_update.php</filename>
    </files>
</extension>

mod_db_update.php

<?php
defined('_JEXEC') or die('Restricted Access');

use Joomla\CMS\Factory;

$db = Factory::getDbo();

$me = Factory::getUser();

if ($me->id == 0)
{
	echo "Not logged on!";
}
else
{
	$email = $me->email; 
	// change the case of the email address
	$email_uppercase = strtoupper($email);
	if ($email == $email_uppercase)
	{
		$new_email = strtolower($email);
	}
	else
	{
		$new_email = $email_uppercase;
	}
	
	$query = $db->getQuery(true);

	$fields = array($db->quoteName('email') . " = '{$new_email}'");

	$conditions = array($db->quoteName('id') . ' = ' . $me->id); 

	$query->update($db->quoteName('#__users'))->set($fields)->where($conditions);

	echo $db->replacePrefix((string) $query);
	
	$db->setQuery($query);

	if ($result = $db->execute())
	{
		echo "Email case successfully changed!";
	}
}

The code above updates the email address field in the users record of the currently logged-on user, toggling between upper case and lower case in successive reloads of the web page. The method Factory::getUser() returns the user object of the currently logged-on user, or if not logged on, then a blank user object, whose id field is set to zero. The $db->replacePrefix((string) $query) expression returns the actual SQL statement, and outputting this can be useful in debugging.

Zip up the mod_db_update directory to create mod_db_update.zip.

Within your Joomla administrator go to Install Extensions and via the Upload Package File tab upload this zip file to install this sample log module.

Make this module visible by editing it (click on it within the Modules page) then:

1. making its status Published
2. selecting a position on the page for it to be shown
3. on the menu assignment tab specify the pages it should appear on

When you visit a site web page then you should see the module in your selected position, and it should output the SQL UPDATE statement and affirm that it has updated the record successfully. To confirm that it has updated the record correctly go into phpmyadmin and view the users table within the Joomla database. The updates aren't visible via the admin Users functionality on the back end, as Joomla displays in lower case all the email addresses in the records.