WordPress Upload Prefilter -toiminnot

WordPressin tiedostojen lataaminen näyttää käyttäjälle yksinkertaiselta toiminnolta: tiedosto valitaan, lataus käynnistyy ja lopuksi tiedosto ilmestyy mediakirjastoon. Kehittäjän näkökulmasta latausprosessi sisältää kuitenkin useita vaiheita, joissa tiedostoa voidaan tarkistaa, muokata tai estää.

Yksi hyödyllisimmistä kohdista tähän on Upload Prefilter eli wp_handle_upload_prefilter-suodatin.

Sen avulla voidaan tarkistaa ladattava tiedosto ennen kuin WordPress käsittelee sen varsinaisena palvelimelle tallennettavana tiedostona.

Mikä on `wp_handle_upload_prefilter`?

wp_handle_upload_prefilter on WordPressin filter-hook, jota voidaan käyttää tiedoston latausprosessin aikana.

Sen avulla voidaan esimerkiksi:

tarkistaa tiedoston nimi
estää tiettyjä tiedostoja
muuttaa tiedoston nimeä
tarkistaa tiedoston koko
toteuttaa omia liiketoimintasääntöjä
estää epätoivotut tiedostotyypit
lisätä mukautettua validointia

Hook vastaanottaa tiedostoa kuvaavan taulukon ennen varsinaista upload-käsittelyä.

Missä vaiheessa prefilter toimii?

Upload-prosessia voidaan yksinkertaistaa näin:

Tiedosto valitaan → WordPress käsittelee upload-tiedot → prefilter → tiedosto tallennetaan → attachment luodaan → metadata muodostetaan

Prefilter on siis hyvä kohta tehdä tarkistuksia ennen kuin tiedosto päätyy lopulliseen tallennusprosessiin.

Se ei kuitenkaan ole koko WordPressin upload-tietoturva. Tiedoston MIME-tyyppi, käyttäjän oikeudet ja muut WordPressin tarkistukset ovat edelleen tärkeitä.

`wp_handle_upload_prefilter` käytännössä

Hook otetaan käyttöön esimerkiksi näin:

add_filter( ’wp_handle_upload_prefilter’, ’my_upload_prefilter’ );

function my_upload_prefilter( $file ) {

// Tarkistukset tähän.

return $file;

}

$file sisältää tietoja ladattavasta tiedostosta.

Tyypillisesti mukana ovat esimerkiksi:

$file[’name’];

$file[’type’];

$file[’tmp_name’];

$file[’error’];

$file[’size’];

Tarkka sisältö riippuu upload-prosessista ja siitä, missä vaiheessa hookia käytetään.

Tiedoston koon tarkistaminen

Prefilter sopii hyvin tilanteisiin, joissa halutaan asettaa oma tiedostokokoraja.

Esimerkiksi:

add_filter( ’wp_handle_upload_prefilter’, ’my_upload_size_check’ );

function my_upload_size_check( $file ) {

$max_size = 5 * MB_IN_BYTES;

if ( $file[’size’] > $max_size ) {

$file[’error’] = ’Tiedosto on liian suuri. Suurin sallittu koko on 5 MB.’;

}

return $file;

}

Kun error-kenttään asetetaan virhe, WordPress voi pysäyttää kyseisen tiedoston käsittelyn.

Miksi tiedoston kokoa kannattaa tarkistaa?

WordPressillä on jo omia upload-rajoituksia, mutta sovelluskohtainen rajoitus voi olla hyödyllinen.

Esimerkiksi yrityksen sivustolla voidaan haluta:

kuville 10 MB:n raja
PDF-tiedostoille 20 MB:n raja
CSV-tiedostoille 5 MB:n raja

Tällöin kannattaa huomioida myös palvelimen omat PHP- ja web-palvelimen rajoitukset.

Prefilter ei voi ohittaa palvelimen rajoituksia, jos tiedosto ei pääse WordPressille asti.

Tiedostonimen tarkistaminen

Tiedostonimi voidaan tarkistaa ennen tallennusta.

Esimerkiksi:

add_filter( ’wp_handle_upload_prefilter’, ’my_filename_check’ );

function my_filename_check( $file ) {

if ( str_contains( $file[’name’], ’ ’ ) ) {

$file[’error’] = ’Tiedostonimessä ei saa olla välilyöntejä.’;

}

return $file;

}

Käytännössä WordPress sanitioi tiedostonimiä jo omassa prosessissaan, joten omaa sääntöä tarvitaan lähinnä silloin, kun projektilla on erityinen nimeämiskäytäntö.

Tiedostonimen muuttaminen

Prefilterillä voidaan myös muuttaa tiedoston nimeä.

add_filter( ’wp_handle_upload_prefilter’, ’my_upload_filename’ );

function my_upload_filename( $file ) {

$extension = pathinfo( $file[’name’], PATHINFO_EXTENSION );

$file[’name’] = ’upload-’ . time() . ’.’ . $extension;

return $file;

}

Tällaisessa ratkaisussa kannattaa kuitenkin välttää liian yksinkertaisia nimeämismalleja.

Esimerkiksi pelkkä time() ei takaa yksilöllistä nimeä tilanteissa, joissa useita tiedostoja käsitellään nopeasti peräkkäin.

Tiedostojen estäminen

Prefilter voi estää tiettyjä tiedostoja esimerkiksi nimen perusteella.

add_filter( ’wp_handle_upload_prefilter’, ’my_blocked_filename’ );

function my_blocked_filename( $file ) {

if ( str_contains( strtolower( $file[’name’] ), ’testi’ ) ) {

$file[’error’] = ’Tämän niminen tiedosto ei ole sallittu.’;

}

return $file;

}

Tämä on kuitenkin lähinnä liiketoimintalogiikkaa. Tietoturvaa ei pidä rakentaa pelkästään tiedostonimen perusteella.

Tiedostotyypin tarkistaminen

Tiedostotyypin tarkistaminen on turvallisuuden kannalta tärkeämpi asia kuin tiedoston nimi.

Esimerkiksi:

add_filter( ’wp_handle_upload_prefilter’, ’my_upload_type_check’ );

function my_upload_type_check( $file ) {

$allowed_types = [

’image/jpeg’,

’image/png’,

’image/webp’,

];

if ( ! in_array( $file[’type’], $allowed_types, true ) ) {

$file[’error’] = ’Tämän tyyppisiä tiedostoja ei voi ladata.’;

}

return $file;

}

Tätä ei kuitenkaan pidä pitää ainoana tiedostotyypin turvatarkistuksena.

WordPressin oma upload-validointi kannattaa säilyttää.

Prefilter ei korvaa tietoturvatarkistuksia

Tämä on tärkeä ero.

wp_handle_upload_prefilter mahdollistaa oman tarkistuksen, mutta se ei tarkoita, että kehittäjän pitäisi rakentaa koko upload-järjestelmä uudelleen.

WordPressissä on jo mekanismeja esimerkiksi:

tiedostotyyppien tarkistamiseen
MIME-tyyppien käsittelyyn
käyttäjän käyttöoikeuksiin
tiedostojen nimien sanitointiin
upload-hakemiston hallintaan

Omat tarkistukset kannattaa rakentaa näiden päälle.

Käyttöoikeuksien tarkistaminen

Jos uploadia käsitellään mukautetussa toiminnossa, käyttäjän oikeudet pitää tarkistaa.

Esimerkiksi:

if ( ! current_user_can( ’upload_files’ ) ) {

return $file;

}

Oikea tarkistus riippuu siitä, mitä toiminnallisuutta ollaan toteuttamassa.

Pelkkään frontendissä piilotettuun upload-kenttään ei saa luottaa käyttöoikeuksien valvonnassa.

Tiedoston sisältö vs. MIME-tyyppi

Tiedoston pääte tai ilmoitettu MIME-tyyppi ei yksin kerro varmasti, mitä tiedosto sisältää.

Esimerkiksi tiedosto voidaan nimetä:

kuva.jpg

vaikka sen sisältö ei olisi oikeasti JPEG-kuva.

Siksi tietoturvakriittisissä ratkaisuissa tiedoston sisältö kannattaa validoida käyttötarkoituksen mukaisesti.

Kuville voidaan esimerkiksi käyttää WordPressin kuva- ja MIME-käsittelyä sen sijaan, että luotetaan pelkkään tiedostonimeen.

Prefilter ja kuvat

Kuvien upload-prosessissa prefilter voi olla hyödyllinen esimerkiksi:

tiedostokoon rajoittamiseen
tietyn nimeämismallin pakottamiseen
tiettyjen tiedostojen estämiseen
projektikohtaisten sääntöjen toteuttamiseen

Sen jälkeen WordPress voi käsitellä kuvan ja muodostaa siitä tarvittavat kuvakoot.

Prefilter ja WooCommerce

WooCommerce-sivustolla tiedostojen lataamiseen voi liittyä esimerkiksi:

tuoteliitteitä
ladattavia tuotteita
tuotemateriaaleja
toimittajien tiedostoja
CSV-tuonteja

Prefilterillä voidaan toteuttaa projektikohtaisia rajoituksia ennen tiedoston varsinaista tallennusta.

Jos kyseessä on WooCommercen oma erityinen upload-prosessi, pitää kuitenkin tarkistaa, kulkeeko kyseinen tiedosto juuri tämän WordPress-upload-hookin kautta.

Prefilter ja CSV-tiedostot

CSV-tiedostojen kohdalla voidaan esimerkiksi tarkistaa koko tai nimi ennen käsittelyä.

Varsinainen CSV-sisällön validointi kannattaa tehdä erillisessä vaiheessa.

Esimerkiksi:

Prefilter → tiedoston perustarkistus → CSV-parseri → rivien validointi → tietojen tallennus

Näin upload-vaihe ja datan käsittely pysyvät erillään.

Virheilmoituksen muodostaminen

Jos tiedosto ei täytä ehtoja, voidaan asettaa $file['error'].

Esimerkiksi:

$file[’error’] = ’Tiedoston koko ylittää sallitun rajan.’;

WordPress käsittelee tämän upload-virheenä.

Käyttäjälle kannattaa antaa mahdollisimman selkeä ilmoitus siitä, miksi tiedostoa ei hyväksytty.

Hookin rajaus

Jos oma tarkistus koskee vain tiettyä toimintoa, globaalisti kaikkiin upload-tapahtumiin vaikuttavaa filtteriä kannattaa käyttää harkiten.

Esimerkiksi lisäosa voi vahingossa rajoittaa:

Media Library -uploadia
WooCommerce-uploadia
REST API -uploadia
muiden lisäosien tiedostolatauksia

Siksi kannattaa selvittää ensin, missä kontekstissa oma sääntö todella tarvitaan.

Suorituskyky

Prefilter suoritetaan upload-prosessin yhteydessä, joten sen sisällä kannattaa välttää raskasta käsittelyä.

Vältä esimerkiksi:

suuria tietokantakyselyitä
hitaita ulkoisia API-kutsuja
koko tiedoston raskasta analysointia ilman tarvetta
monimutkaista laskentaa

Prefilterin kannattaa olla mahdollisimman nopea.

Jos tiedostolle tarvitaan raskasta analytiikkaa, se voidaan usein tehdä myöhemmin taustaprosessina.

Yleisimmät virheet

wp_handle_upload_prefilter-hookin käytössä tehdään helposti muutamia virheitä.

Tyypillisiä ovat:

luotetaan vain tiedostonimeen
käytetään MIME-tyyppiä ainoana turvatarkistuksena
ohitetaan WordPressin omat upload-tarkistukset
tehdään liian raskasta työtä prefilterissä
vaikutetaan vahingossa kaikkiin sivuston upload-toimintoihin
unohdetaan käyttöoikeuksien tarkistaminen mukautetussa upload-prosessissa

Hyvä prefilter täydentää WordPressin upload-järjestelmää eikä yritä korvata sitä.

Parhaat käytännöt

WordPress Upload Prefilter -toimintoja käytettäessä kannattaa:

käytä wp_handle_upload_prefilter-hookia tarkasti rajattuihin sääntöihin
säilytä WordPressin oma tiedostovalidointi
tarkista tiedostokoko tarvittaessa
käsittele tiedostonimet turvallisesti
älä luota pelkkään MIME-tyyppiin
tarkista käyttöoikeudet mukautetuissa prosesseissa
pidä prefilter nopeana
testaa eri tiedostotyypeillä
huomioi muiden lisäosien upload-prosessit

Milloin Upload Prefilter on hyödyllinen?

wp_handle_upload_prefilter sopii erityisesti silloin, kun WordPressin tavallisen upload-prosessin päälle tarvitaan oma sääntö.

Hyviä käyttökohteita ovat:

tiedostokokojen rajoittaminen
projektikohtaiset nimeämissäännöt
tiettyjen tiedostojen estäminen
organisaation upload-käytäntöjen toteuttaminen
mukautettujen validointisääntöjen lisääminen
mediakirjaston hallinnan laajentaminen

Se on pieni hook, mutta oikein käytettynä erittäin hyödyllinen osa WordPressin tiedostojen käsittelyä.

Yhteenveto

WordPressin wp_handle_upload_prefilter tarjoaa kehittäjälle mahdollisuuden vaikuttaa tiedoston upload-prosessiin ennen varsinaista tallennusta. Sen avulla voidaan tarkistaa esimerkiksi tiedoston koko, nimi ja muut projektikohtaiset ehdot sekä pysäyttää tiedosto tarvittaessa virheilmoituksella.

Prefilter kannattaa kuitenkin nähdä yhtenä osana WordPressin upload-ketjua, ei itsenäisenä tietoturvaratkaisuna. Kun se yhdistetään WordPressin omiin MIME-, käyttöoikeus- ja tiedostotarkistuksiin, voidaan rakentaa hallittu upload-prosessi ilman, että WordPressin normaalia toimintaa tarvitsee kiertää.

Metakuvaus:

Tutustu WordPressin wp_handle_upload_prefilter-hookiin. Opas kertoo, miten tiedostojen kokoa, nimeä ja tyyppiä voidaan tarkistaa ennen uploadia sekä miten turvallinen tiedostojen käsittely toteutetaan.

🤖 Tämä sisältö on tuotettu tekoälyn avulla. Tarkista tiedot alkuperäisistä lähteistä ennen niiden hyödyntämistä.

WordPress Upload Prefilter -toiminnot

WordPress Upload Prefilter -toiminnot

Mikä on `wp_handle_upload_prefilter`?

Missä vaiheessa prefilter toimii?

`wp_handle_upload_prefilter` käytännössä

Tiedoston koon tarkistaminen

Miksi tiedoston kokoa kannattaa tarkistaa?

Tiedostonimen tarkistaminen

Tiedostonimen muuttaminen

Tiedostojen estäminen

Tiedostotyypin tarkistaminen

Prefilter ei korvaa tietoturvatarkistuksia

Käyttöoikeuksien tarkistaminen

Tiedoston sisältö vs. MIME-tyyppi

Prefilter ja kuvat

Prefilter ja WooCommerce

Prefilter ja CSV-tiedostot

Virheilmoituksen muodostaminen

Hookin rajaus

Suorituskyky

Yleisimmät virheet

Parhaat käytännöt

Milloin Upload Prefilter on hyödyllinen?

Yhteenveto